PageRenderTime 25ms CodeModel.GetById 15ms app.highlight 6ms RepoModel.GetById 1ms app.codeStats 0ms

/lfw/rocks/luafilesystem/1.5.0-1/doc/us/manual.html

http://github.com/keplerproject/luarocks
HTML | 271 lines | 223 code | 48 blank | 0 comment | 0 complexity | 4ce5fbcb073538cb5509c20e7fa4b13b MD5 | raw file
  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
 61developed to complement the set of functions related to file
 62systems offered by the standard Lua distribution.</p>
 63
 64<p>LuaFileSystem offers a portable way to access
 65the underlying directory structure and file attributes.</p>
 66
 67<h2><a name="building"></a>Building</h2>
 68
 69<p>
 70LuaFileSystem should be built with Lua 5.1 so the language library
 71and header files for the target version must be installed properly.
 72</p>
 73
 74<p>
 75LuaFileSystem offers a Makefile and a separate configuration file,
 76<code>config</code>,
 77which should be edited to suit your installation before running
 78<code>make</code>.
 79The file has some definitions like paths to the external libraries,
 80compiler options and the like.
 81</p>
 82
 83<p>On Windows, the C runtime used to compile LuaFileSystem must be the same
 84runtime 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">
 91luarocks 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>
100LuaFileSystem 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>