aboutsummaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/doc.css209
-rw-r--r--docs/examples.html101
-rw-r--r--docs/index.html230
-rw-r--r--docs/license.html108
-rw-r--r--docs/luafilesystem.pngbin0 -> 8535 bytes
-rw-r--r--docs/manual.html286
6 files changed, 934 insertions, 0 deletions
diff --git a/docs/doc.css b/docs/doc.css
new file mode 100644
index 0000000..f233ce4
--- /dev/null
+++ b/docs/doc.css
@@ -0,0 +1,209 @@
1body {
2 color: #47555c;
3 font-size: 16px;
4 font-family: "Open Sans", sans-serif;
5 margin: 0;
6 padding: 0;
7 background: #eff4ff;
8}
9
10a:link { color: #008fee; }
11a:visited { color: #008fee; }
12a:hover { color: #22a7ff; }
13
14h1 { font-size:26px; }
15h2 { font-size:24px; }
16h3 { font-size:18px; }
17h4 { font-size:16px; }
18
19hr {
20 height: 1px;
21 background: #c1cce4;
22 border: 0px;
23 margin: 20px 0;
24}
25
26code {
27 font-family: "Open Sans Mono", "Andale Mono", monospace;
28}
29
30tt {
31 font-family: "Open Sans Mono", "Andale Mono", monospace;
32}
33
34body, td, th {
35}
36
37textarea, pre, tt {
38 font-family: "Open Sans Mono", "Andale Mono", monospace;
39}
40
41img {
42 border-width: 0px;
43}
44
45.example {
46 background-color: #323744;
47 color: white;
48 font-size: 16px;
49 padding: 16px 24px;
50 border-radius: 2px;
51}
52
53div.header, div.footer {
54}
55
56#container {
57}
58
59#product {
60 background-color: white;
61 padding: 10px;
62 height: 130px;
63 border-bottom: solid #d3dbec 1px;
64}
65
66#product big {
67 font-size: 42px;
68}
69#product strong {
70 font-weight: normal;
71}
72
73#product_logo {
74 float: right;
75}
76
77#product_name {
78 padding-top: 15px;
79 padding-left: 30px;
80 font-size: 42px;
81 font-weight: normal;
82}
83
84#product_description {
85 padding-left: 30px;
86 color: #757779;
87}
88
89#main {
90 background: #eff4ff;
91 margin: 0;
92}
93
94#navigation {
95 width: 100%;
96 background-color: rgb(44,62,103);
97 padding: 10px;
98 margin: 0;
99}
100
101#navigation h1 {
102 display: none;
103}
104
105#navigation a:hover {
106 text-decoration: underline;
107}
108
109#navigation ul li a {
110 color: rgb(136, 208, 255);
111 font-weight: bold;
112 text-decoration: none;
113}
114
115#navigation ul li li a {
116 color: rgb(136, 208, 255);
117 font-weight: normal;
118 text-decoration: none;
119}
120
121#navigation ul {
122 display: inline;
123 color: white;
124 padding: 0px;
125 padding-top: 10px;
126 padding-bottom: 10px;
127}
128
129#navigation li {
130 display: inline;
131 list-style-type: none;
132 padding-left: 5px;
133 padding-right: 5px;
134}
135
136#navigation li {
137 padding: 10px;
138 padding: 10px;
139}
140
141#navigation li li {
142}
143
144#navigation li:hover a {
145 color: rgb(166, 238, 255);
146}
147
148#content {
149 padding: 20px;
150 width: 800px;
151 margin-left: auto;
152 margin-right: auto;
153}
154
155#about {
156 display: none;
157}
158
159dl.reference {
160 background-color: white;
161 padding: 20px;
162 border: solid #d3dbec 1px;
163}
164
165dl.reference dt {
166 padding: 5px;
167 padding-top: 25px;
168 color: #637bbc;
169}
170
171dl.reference dl dt {
172 padding-top: 5px;
173 color: #637383;
174}
175
176dl.reference dd {
177}
178
179@media print {
180 body {
181 font: 10pt "Times New Roman", "TimeNR", Times, serif;
182 }
183 a {
184 font-weight:bold; color: #004080; text-decoration: underline;
185 }
186 #main {
187 background-color: #ffffff; border-left: 0px;
188 }
189 #container {
190 margin-left: 2%; margin-right: 2%; background-color: #ffffff;
191 }
192 #content {
193 margin-left: 0px; padding: 1em; border-left: 0px; border-right: 0px; background-color: #ffffff;
194 }
195 #navigation {
196 display: none;
197 }
198 #product_logo {
199 display: none;
200 }
201 #about img {
202 display: none;
203 }
204 .example {
205 font-family: "Andale Mono", monospace;
206 font-size: 8pt;
207 page-break-inside: avoid;
208 }
209}
diff --git a/docs/examples.html b/docs/examples.html
new file mode 100644
index 0000000..68756c8
--- /dev/null
+++ b/docs/examples.html
@@ -0,0 +1,101 @@
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><a href="manual.html">Manual</a>
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><strong>Examples</strong></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="example"></a>Examples</h2>
60
61<h3>Directory iterator</h3>
62
63<p>The following example iterates over a directory and recursively lists the
64attributes for each file inside it.</p>
65
66<pre class="example">
67local lfs = require"lfs"
68
69function attrdir (path)
70 for file in lfs.dir(path) do
71 if file ~= "." and file ~= ".." then
72 local f = path..'/'..file
73 print ("\t "..f)
74 local attr = lfs.attributes (f)
75 assert (type(attr) == "table")
76 if attr.mode == "directory" then
77 attrdir (f)
78 else
79 for name, value in pairs(attr) do
80 print (name, value)
81 end
82 end
83 end
84 end
85end
86
87attrdir (".")
88</pre>
89
90</div> <!-- id="content" -->
91
92</div> <!-- id="main" -->
93
94<div id="about">
95 <p><a href="http://validator.w3.org/check?uri=referer">Valid XHTML 1.0!</a></p>
96</div> <!-- id="about" -->
97
98</div> <!-- id="container" -->
99
100</body>
101</html>
diff --git a/docs/index.html b/docs/index.html
new file mode 100644
index 0000000..b4f056e
--- /dev/null
+++ b/docs/index.html
@@ -0,0 +1,230 @@
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><strong>Home</strong>
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><a href="manual.html">Manual</a>
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="overview"></a>Overview</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<p>LuaFileSystem is free software and uses the same
69<a href="license.html">license</a> as Lua 5.x (MIT).</p>
70
71<h2><a name="status"></a>Status</h2>
72
73<p>Current version is 1.8.0. It works with Lua 5.1, 5.2, 5.3 and 5.4, and it runs on various
74flavors of Unix (including Linux, BSDs, macOS) and Windows.</p>
75
76<h2><a name="download"></a>Download</h2>
77
78<p>LuaFileSystem can be installed using <a href="https://luarocks.org">LuaRocks</a>:
79
80<pre class="example">
81$ luarocks install luafilesystem
82</pre>
83
84<p>Its source can be found at its <a href="http://github.com/keplerproject/luafilesystem">GitHub</a> page.</p>
85
86<h2><a name="history"></a>History</h2>
87
88<dl class="history">
89 <dt><strong>Version 1.8.0</strong> [22/Apr/2020]</dt>
90 <dd><ul>
91 <li>Lua 5.4 support</li>
92 <li>lfs.link and lfs.symlinkattributes now work on Windows</li>
93 <li>MACOSX_DEPLOYMENT_TARGET is configurable in the Makefile</li>
94 <li>Fallback to _POSIX_PATH_MAX when MAXPATHLEN is not avaliable</li>
95 <li>Fixed memory leak in case of realloc failure</li>
96 </ul></dd>
97
98 <dt><strong>Version 1.7.0</strong> [15/Sep/2017]</dt>
99 <dd><ul>
100 <li>symlinkattributes function now provides 'target' field, containing name of the file that the symlink points to.</li>
101 <li>attributes, symlinkattributes, touch, mkdir, and rmdir functions now return system-dependent error code as the third value on error.</li>
102 <li>Fixed detection of closed files for Lua 5.2+ in setmode, lock, and unlock functions.</li>
103 <li>Fixed various compiler warnings.</li>
104 </ul></dd>
105
106 <dt><strong>Version 1.6.3</strong> [15/Jan/2015]</dt>
107 <dd><ul>
108 <li>Lua 5.3 support.</li>
109 <li>Assorted bugfixes.</li>
110 </ul></dd>
111
112 <dt><strong>Version 1.6.2</strong> [??/Oct/2012]</dt>
113 <dd><ul>
114 <li>Full Lua 5.2 compatibility (with Lua 5.1 fallbacks)</li>
115 </ul></dd>
116
117 <dt><strong>Version 1.6.1</strong> [01/Oct/2012]</dt>
118 <dd><ul>
119 <li>fix build for Lua 5.2</li>
120 </ul></dd>
121
122 <dt><strong>Version 1.6.0</strong> [26/Sep/2012]</dt>
123 <dd><ul>
124 <li>getcwd fix for Android</li>
125 <li>support for Lua 5.2</li>
126 <li>add lfs.link</li>
127 <li>other bug fixes</li>
128 </ul></dd>
129
130 <dt><strong>Version 1.5.0</strong> [20/Oct/2009]</dt>
131 <dd><ul>
132 <li>Added explicit next and close methods to second return value of lfs.dir
133(the directory object), for explicit iteration or explicit closing.</li>
134 <li>Added directory locking via lfs.lock_dir function (see the <a href="manual.html">manual</a>).</li>
135 </ul></dd>
136 <dt><strong>Version 1.4.2</strong> [03/Feb/2009]</dt>
137 <dd>
138 <ul>
139 <li>fixed bug
140 <code>lfs.attributes(filename, 'size')</code> overflow on files > 2 Gb again (bug report and patch by KUBO Takehiro).</li>
141 <li>fixed bug
142 Compile error on Solaris 10 (bug report and patch by Aaron B).</li>
143 <li>fixed compilation problems with Borland C.</li>
144 </ul>
145 </dd>
146
147 <dt><strong>Version 1.4.1</strong> [07/May/2008]</dt>
148 <dd>
149 <ul>
150 <li>documentation review</li>
151 <li>fixed Windows compilation issues</li>
152 <li>fixed bug in the Windows tests (patch by Shmuel Zeigerman)</li>
153 <li>fixed bug
154 <code>lfs.attributes(filename, 'size')</code> overflow on files > 2 Gb
155 </li>
156 </ul>
157 </dd>
158
159 <dt><strong>Version 1.4.0</strong> [13/Feb/2008]</dt>
160 <dd>
161 <ul>
162 <li>added function
163 <a href="manual.html#setmode"><code>lfs.setmode</code></a>
164 (works only in Windows systems).</li>
165 <li><a href="manual.html#attributes"><code>lfs.attributes</code></a>
166 raises an error if attribute does not exist</li>
167 </ul>
168 </dd>
169
170 <dt><strong>Version 1.3.0</strong> [26/Oct/2007]</dt>
171 <dd>
172 <ul>
173 <li>added function
174 <a href="manual.html#symlinkattributes"><code>lfs.symlinkattributes</code></a>
175 (works only in non Windows systems).</li>
176 </ul>
177 </dd>
178
179 <dt><strong>Version 1.2.1</strong> [08/May/2007]</dt>
180 <dd>
181 <ul>
182 <li>compatible only with Lua 5.1 (Lua 5.0 support was dropped)</li>
183 </ul>
184 </dd>
185
186 <dt><strong>Version 1.2</strong> [15/Mar/2006]</dt>
187 <dd>
188 <ul>
189 <li>added optional argument to
190 <a href="manual.html#attributes"><code>lfs.attributes</code></a></li>
191 <li>added function
192 <a href="manual.html#rmdir"><code>lfs.rmdir</code></a></li>
193 <li>bug correction on <a href="manual.html#dir"><code>lfs.dir</code></a></li>
194 </ul>
195 </dd>
196
197 <dt><strong>Version 1.1</strong> [30/May/2005]</dt>
198 <dd>
199 <ul>
200 <li>added function <a href="manual.html#touch"><code>lfs.touch</code></a>.</li>
201 </ul>
202 </dd>
203
204 <dt><strong>Version 1.0</strong> [21/Jan/2005]</dt>
205 <dd />
206
207 <dt><strong>Version 1.0 Beta</strong> [10/Nov/2004]</dt>
208 <dd />
209</dl>
210
211<h2><a name="credits"></a>Credits</h2>
212
213<p>The LuaFileSystem library was originally designed and
214implemented by Roberto Ierusalimschy, Andr&eacute; Carregal and
215Tom&aacute;s Guisasola. It was then maintained by F&aacute;bio
216Mascarenhas for several years and has since been maintained
217by many contributors -- see the Git history for detailed credits.</p>
218
219</div> <!-- id="content" -->
220
221</div> <!-- id="main" -->
222
223<div id="about">
224 <p><a href="http://validator.w3.org/check?uri=referer">Valid XHTML 1.0!</a></p>
225</div> <!-- id="about" -->
226
227</div> <!-- id="container" -->
228
229</body>
230</html>
diff --git a/docs/license.html b/docs/license.html
new file mode 100644
index 0000000..bb66e48
--- /dev/null
+++ b/docs/license.html
@@ -0,0 +1,108 @@
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><a href="manual.html">Manual</a>
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><strong>License</strong></li>
54 </ul>
55</div> <!-- id="navigation" -->
56
57<div id="content">
58
59<h1>License</h1>
60
61<p>The spirit of the license is that you are free to use
62LuaFileSystem for any purpose at no cost without having to ask us.
63The only requirement is that if you do use LuaFileSystem, then you
64should give us credit by including the appropriate copyright notice
65somewhere in your product or its documentation.</p>
66
67<p>The LuaFileSystem library was originally designed and
68implemented by Roberto Ierusalimschy, Andr&eacute; Carregal and
69Tom&aacute;s Guisasola, and has since been maintained over the years
70by many people -- see the Git history for detailed credits.
71The implementation is not derived from any other licensed software.</p>
72
73<hr/>
74<p>Copyright &copy; 2003 - 2014 Kepler Project.</p>
75<p>Copyright &copy; 2014 - 2022 The LuaFileSystem authors.</p>
76
77<p>Permission is hereby granted, free of charge, to any person
78obtaining a copy of this software and associated documentation
79files (the "Software"), to deal in the Software without
80restriction, including without limitation the rights to use, copy,
81modify, merge, publish, distribute, sublicense, and/or sell copies
82of the Software, and to permit persons to whom the Software is
83furnished to do so, subject to the following conditions:</p>
84
85<p>The above copyright notice and this permission notice shall be
86included in all copies or substantial portions of the Software.</p>
87
88<p>THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
89EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
90MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
91NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
92BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
93ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
94CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
95SOFTWARE.</p>
96
97</div> <!-- id="content" -->
98
99</div> <!-- id="main" -->
100
101<div id="about">
102 <p><a href="http://validator.w3.org/check?uri=referer">Valid XHTML 1.0!</a></p>
103</div><!-- id="about" -->
104
105</div><!-- id="container" -->
106
107</body>
108</html>
diff --git a/docs/luafilesystem.png b/docs/luafilesystem.png
new file mode 100644
index 0000000..e1dd8c6
--- /dev/null
+++ b/docs/luafilesystem.png
Binary files differ
diff --git a/docs/manual.html b/docs/manual.html
new file mode 100644
index 0000000..1feb86a
--- /dev/null
+++ b/docs/manual.html
@@ -0,0 +1,286 @@
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-03-26 17:57:31 +0000