source/texk/web2c/luatexdir/luafilesystem/doc/us/manual.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   2    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5         <title>LuaFileSystem</title>
   6     <link rel="stylesheet" href="http://www.keplerproject.org/doc.css" type="text/css"/>
   7         <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
   8 </head>
   9
  10 <body>
  11
  12 <div id="container">
  13
  14 <div id="product">
  15         <div id="product_logo">
  16         <a href="http://www.keplerproject.org"><img alt="LuaFileSystem" src="luafilesystem.png"/></a>
  17     </div>
  18         <div id="product_name"><big><strong>LuaFileSystem</strong></big></div>
  19         <div id="product_description">File System Library for the Lua Programming Language</div>
  20 </div> <!-- id="product" -->
  21
  22 <div id="main">
  23
  24 <div id="navigation">
  25 <h1>LuaFileSystem</h1>
  26         <ul>
  27                 <li><a href="index.html">Home</a>
  28                         <ul>
  29                                 <li><a href="index.html#overview">Overview</a></li>
  30                                 <li><a href="index.html#status">Status</a></li>
  31                                 <li><a href="index.html#download">Download</a></li>
  32                                 <li><a href="index.html#history">History</a></li>
  33                                 <li><a href="index.html#credits">Credits</a></li>
  34                                 <li><a href="index.html#contact">Contact us</a></li>
  35                         </ul>
  36                 </li>
  37                 <li><strong>Manual</strong>
  38                         <ul>
  39                                 <li><a href="manual.html#introduction">Introduction</a></li>
  40                                 <li><a href="manual.html#building">Building</a></li>
  41                                 <li><a href="manual.html#installation">Installation</a></li>
  42                                 <li><a href="manual.html#reference">Reference</a></li>
  43                         </ul>
  44                 </li>
  45                 <li><a href="examples.html">Examples</a></li>
  46         <li><a href="http://luaforge.net/projects/luafilesystem/">Project</a>
  47             <ul>
  48                 <li><a href="http://luaforge.net/tracker/?group_id=66">Bug Tracker</a></li>
  49                 <li><a href="http://luaforge.net/scm/?group_id=66">CVS</a></li>
  50             </ul>
  51         </li>
  52                 <li><a href="license.html">License</a></li>
  53         </ul>
  54 </div> <!-- id="navigation" -->
  55
  56 <div id="content">
  57
  58 <h2><a name="introduction"></a>Introduction</h2>
  59
  60 <p>LuaFileSystem is a <a href="http://www.lua.org">Lua</a> library
  61 developed to complement the set of functions related to file
  62 systems offered by the standard Lua distribution.</p>
  63
  64 <p>LuaFileSystem offers a portable way to access
  65 the underlying directory structure and file attributes.</p>
  66
  67 <h2><a name="building"></a>Building</h2>
  68
  69 <p>
  70 LuaFileSystem should be built with Lua 5.1 so the language library
  71 and header files for the target version must be installed properly.
  72 </p>
  73
  74 <p>
  75 LuaFileSystem offers a Makefile and a separate configuration file,
  76 <code>config</code>,
  77 which should be edited to suit your installation before running
  78 <code>make</code>.
  79 The file has some definitions like paths to the external libraries,
  80 compiler options and the like.
  81 </p>
  82
  83 <p>On Windows, the C runtime used to compile LuaFileSystem must be the same
  84 runtime that Lua uses, or some LuaFileSystem functions will not work.</p>
  85
  86 <h2><a name="installation"></a>Installation</h2>
  87
  88 <p>The easiest way to install LuaFileSystem is to use LuaRocks:</p>
  89
  90 <pre class="example">
  91 luarocks install luafilesystem
  92 </pre>
  93
  94 <p>If you prefer to install LuaFileSystem manually, the compiled binary should be copied to a directory in your
  95 <a href="http://www.lua.org/manual/5.1/manual.html#pdf-package.cpath">C path</a>.</p>
  96
  97 <h2><a name="reference"></a>Reference</h2>
  98
  99 <p>
 100 LuaFileSystem offers the following functions:
 101 </p>
 102
 103 <dl class="reference">
 104     <dt><a name="attributes"></a><strong><code>lfs.attributes (filepath [, aname])</code></strong></dt>
 105     <dd>Returns a table with the file attributes corresponding to
 106     <code>filepath</code> (or <code>nil</code> followed by an error message
 107     in case of error).
 108     If the second optional argument is given, then only the value of the
 109     named attribute is returned (this use is equivalent to
 110     <code>lfs.attributes(filepath).aname</code>, but the table is not created
 111     and only one attribute is retrieved from the O.S.).
 112     The attributes are described as follows;
 113     attribute <code>mode</code> is a string, all the others are numbers,
 114     and the time related attributes use the same time reference of
 115     <a href="http://www.lua.org/manual/5.1/manual.html#pdf-os.time"><code>os.time</code></a>:
 116         <dl>
 117         <dt><strong><code>dev</code></strong></dt>
 118         <dd>on Unix systems, this represents the device that the inode resides on. On Windows systems,
 119         represents the drive number of the disk containing the file</dd>
 120
 121         <dt><strong><code>ino</code></strong></dt>
 122         <dd>on Unix systems, this represents the inode number. On Windows systems this has no meaning</dd>
 123
 124         <dt><strong><code>mode</code></strong></dt>
 125         <dd>string representing the associated protection mode (the values could be
 126         <code>file</code>, <code>directory</code>, <code>link</code>, <code>socket</code>,
 127         <code>named pipe</code>, <code>char device</code>, <code>block device</code> or
 128         <code>other</code>)</dd>
 129
 130         <dt><strong><code>nlink</code></strong></dt>
 131                 <dd>number of hard links to the file</dd>
 132
 133         <dt><strong><code>uid</code></strong></dt>
 134                 <dd>user-id of owner (Unix only, always 0 on Windows)</dd>
 135
 136         <dt><strong><code>gid</code></strong></dt>
 137                 <dd>group-id of owner (Unix only, always 0 on Windows)</dd>
 138
 139         <dt><strong><code>rdev</code></strong></dt>
 140                 <dd>on Unix systems, represents the device type, for special file inodes.
 141         On Windows systems represents the same as <code>dev</code></dd>
 142
 143         <dt><strong><code>access</code></strong></dt>
 144                 <dd>time of last access</dd>
 145
 146         <dt><strong><code>modification</code></strong></dt>
 147                 <dd>time of last data modification</dd>
 148
 149         <dt><strong><code>change</code></strong></dt>
 150                 <dd>time of last file status change</dd>
 151
 152         <dt><strong><code>size</code></strong></dt>
 153                 <dd>file size, in bytes</dd>
 154
 155         <dt><strong><code>blocks</code></strong></dt>
 156                 <dd>block allocated for file; (Unix only)</dd>
 157
 158         <dt><strong><code>blksize</code></strong></dt>
 159                 <dd>optimal file system I/O blocksize; (Unix only)</dd>
 160             </dl>
 161     This function uses <code>stat</code> internally thus if the given
 162     <code>filepath</code> is a symbolic link, it is followed (if it points to
 163     another link the chain is followed recursively) and the information
 164     is about the file it refers to.
 165     To obtain information about the link itself, see function
 166     <a href="#symlinkattributes">lfs.symlinkattributes</a>.
 167         </dd>
 168
 169     <dt><a name="chdir"></a><strong><code>lfs.chdir (path)</code></strong></dt>
 170     <dd>Changes the current working directory to the given
 171     <code>path</code>.<br />
 172     Returns <code>true</code> in case of success or <code>nil</code> plus an
 173     error string.</dd>
 174
 175     <dt><a name="chdir"></a><strong><code>lfs.lock_dir(path, [seconds_stale])</code></strong></dt>
 176     <dd>Creates a lockfile (called lockfile.lfs) in <code>path</code> if it does not
 177   exist and returns the lock. If the lock already exists checks it
 178   it's stale, using the second parameter (default for the second
 179   parameter is <code>INT_MAX</code>, which in practice means the lock will never
 180   be stale. To free the the lock call <code>lock:free()</code>. <br/>
 181    In case of any errors it returns nil and the error message. In
 182   particular, if the lock exists and is not stale it returns the
 183   "File exists" message.</dd>
 184
 185     <dt><a name="getcwd"></a><strong><code>lfs.currentdir ()</code></strong></dt>
 186     <dd>Returns a string with the current working directory or <code>nil</code>
 187     plus an error string.</dd>
 188
 189     <dt><a name="dir"></a><strong><code>iter, dir_obj = lfs.dir (path)</code></strong></dt>
 190     <dd>
 191     Lua iterator over the entries of a given directory.
 192     Each time the iterator is called with <code>dir_obj</code> it returns a directory entry's name as a string, or
 193     <code>nil</code> if there are no more entries. You can also iterate by calling <code>dir_obj:next()</code>, and
 194     explicitly close the directory before the iteration finished with <code>dir_obj:close()</code>.
 195     Raises an error if <code>path</code> is not a directory.
 196     </dd>
 197
 198     <dt><a name="lock"></a><strong><code>lfs.lock (filehandle, mode[, start[, length]])</code></strong></dt>
 199     <dd>Locks a file or a part of it. This function works on <em>open files</em>; the
 200     file handle should be specified as the first argument.
 201     The string <code>mode</code> could be either
 202     <code>r</code> (for a read/shared lock) or <code>w</code> (for a
 203     write/exclusive lock). The optional arguments <code>start</code>
 204     and <code>length</code> can be used to specify a starting point and
 205     its length; both should be numbers.<br />
 206     Returns <code>true</code> if the operation was successful; in
 207     case of error, it returns <code>nil</code> plus an error string.
 208     </dd>
 209
 210     <dt><a name="mkdir"></a><strong><code>lfs.mkdir (dirname)</code></strong></dt>
 211     <dd>Creates a new directory. The argument is the name of the new
 212     directory.<br />
 213     Returns <code>true</code> if the operation was successful;
 214     in case of error, it returns <code>nil</code> plus an error string.
 215     </dd>
 216
 217     <dt><a name="rmdir"></a><strong><code>lfs.rmdir (dirname)</code></strong></dt>
 218     <dd>Removes an existing directory. The argument is the name of the directory.<br />
 219     Returns <code>true</code> if the operation was successful;
 220     in case of error, it returns <code>nil</code> plus an error string.</dd>
 221
 222     <dt><a name="setmode"></a><strong><code>lfs.setmode (file, mode)</code></strong></dt>
 223     <dd>Sets the writing mode for a file. The mode string can be either <code>binary</code> or <code>text</code>.
 224     Returns the previous mode string for the file. This function is only available in Windows, so you may want to make sure that
 225     <code>lfs.setmode</code> exists before using it.
 226     </dd>
 227
 228     <dt><a name="symlinkattributes"></a><strong><code>lfs.symlinkattributes (filepath [, aname])</code></strong></dt>
 229     <dd>Identical to <a href="#attributes">lfs.attributes</a> except that
 230     it obtains information about the link itself (not the file it refers to).
 231     This function is not available in Windows so you may want to make sure that
 232     <code>lfs.symlinkattributes</code> exists before using it.
 233     </dd>
 234
 235     <dt><a name="touch"></a><strong><code>lfs.touch (filepath [, atime [, mtime]])</code></strong></dt>
 236     <dd>Set access and modification times of a file. This function is
 237     a bind to <code>utime</code> function. The first argument is the
 238     filename, the second argument (<code>atime</code>) is the access time,
 239     and the third argument (<code>mtime</code>) is the modification time.
 240     Both times are provided in seconds (which should be generated with
 241     Lua standard function <code>os.time</code>).
 242     If the modification time is omitted, the access time provided is used;
 243     if both times are omitted, the current time is used.<br />
 244     Returns <code>true</code> if the operation was successful;
 245     in case of error, it returns <code>nil</code> plus an error string.
 246     </dd>
 247
 248     <dt><a name="unlock"></a><strong><code>lfs.unlock (filehandle[, start[, length]])</code></strong></dt>
 249     <dd>Unlocks a file or a part of it. This function works on
 250     <em>open files</em>; the file handle should be specified as the first
 251     argument. The optional arguments <code>start</code> and
 252     <code>length</code> can be used to specify a starting point and its
 253     length; both should be numbers.<br />
 254     Returns <code>true</code> if the operation was successful;
 255     in case of error, it returns <code>nil</code> plus an error string.
 256     </dd>
 257 </dl>
 258
 259 </div> <!-- id="content" -->
 260
 261 </div> <!-- id="main" -->
 262
 263 <div id="about">
 264         <p><a href="http://validator.w3.org/check?uri=referer">Valid XHTML 1.0!</a></p>
 265         <p><small>$Id: manual.html,v 1.45 2009/06/03 20:53:55 mascarenhas Exp $</small></p>
 266 </div> <!-- id="about" -->
 267
 268 </div> <!-- id="container" -->
 269
 270 </body>
 271 </html>