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