/Code/Angel/Libraries/lua-libs/luafilesystem-1.5.0/doc/us/manual.html

http://angel-engine.googlecode.com/ · 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. 

  2.    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
    3. 

  3. <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
    4. 

  4. <head>
    5. 

  5. 	<title>LuaFileSystem</title>
    6. 

  6.     <link rel="stylesheet" href="http://www.keplerproject.org/doc.css" type="text/css"/>
    7. 

  7. 	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
    8. 

  8. </head>
    9. 

  9. 

  10. <body>
    11. 

  11. 

  12. <div id="container">
    13. 

  13. 

  14. <div id="product">
    15. 

  15. 	<div id="product_logo">
    16. 

  16.         <a href="http://www.keplerproject.org"><img alt="LuaFileSystem" src="luafilesystem.png"/></a>
    17. 

  17.     </div>
    18. 

  18. 	<div id="product_name"><big><strong>LuaFileSystem</strong></big></div>
    19. 

  19. 	<div id="product_description">File System Library for the Lua Programming Language</div>
    20. 

  20. </div> <!-- id="product" -->
    21. 

  21. 

  22. <div id="main">
    23. 

  23. 	
    24. 

  24. <div id="navigation">
    25. 

  25. <h1>LuaFileSystem</h1>
    26. 

  26. 	<ul>
    27. 

  27. 		<li><a href="index.html">Home</a>
    28. 

  28. 			<ul>
    29. 

  29. 				<li><a href="index.html#overview">Overview</a></li>
    30. 

  30. 				<li><a href="index.html#status">Status</a></li>
    31. 

  31. 				<li><a href="index.html#download">Download</a></li>
    32. 

  32. 				<li><a href="index.html#history">History</a></li>
    33. 

  33. 				<li><a href="index.html#credits">Credits</a></li>
    34. 

  34. 				<li><a href="index.html#contact">Contact us</a></li>
    35. 

  35. 			</ul>
    36. 

  36. 		</li>
    37. 

  37. 		<li><strong>Manual</strong>
    38. 

  38. 			<ul>
    39. 

  39. 				<li><a href="manual.html#introduction">Introduction</a></li>
    40. 

  40. 				<li><a href="manual.html#building">Building</a></li>
    41. 

  41. 				<li><a href="manual.html#installation">Installation</a></li>
    42. 

  42. 				<li><a href="manual.html#reference">Reference</a></li>
    43. 

  43. 			</ul>
    44. 

  44. 		</li>
    45. 

  45. 		<li><a href="examples.html">Examples</a></li>
    46. 

  46.         <li><a href="http://luaforge.net/projects/luafilesystem/">Project</a>
    47. 

  47.             <ul>
    48. 

  48.                 <li><a href="http://luaforge.net/tracker/?group_id=66">Bug Tracker</a></li>
    49. 

  49.                 <li><a href="http://luaforge.net/scm/?group_id=66">CVS</a></li>
    50. 

  50.             </ul>
    51. 

  51.         </li>
    52. 

  52. 		<li><a href="license.html">License</a></li>
    53. 

  53. 	</ul>
    54. 

  54. </div> <!-- id="navigation" -->
    55. 

  55. 

  56. <div id="content">
    57. 

  57. 

  58. <h2><a name="introduction"></a>Introduction</h2>
    59. 

  59. 

  60. <p>LuaFileSystem is a <a href="http://www.lua.org">Lua</a> library
    61. 

  61. developed to complement the set of functions related to file
    62. 

  62. systems offered by the standard Lua distribution.</p>
    63. 

  63. 

  64. <p>LuaFileSystem offers a portable way to access
    65. 

  65. the underlying directory structure and file attributes.</p>
    66. 

  66. 

  67. <h2><a name="building"></a>Building</h2>
    68. 

  68. 

  69. <p>
    70. 

  70. LuaFileSystem should be built with Lua 5.1 so the language library
    71. 

  71. and header files for the target version must be installed properly.
    72. 

  72. </p>
    73. 

  73. 

  74. <p>
    75. 

  75. LuaFileSystem offers a Makefile and a separate configuration file,
    76. 

  76. <code>config</code>,
    77. 

  77. which should be edited to suit your installation before running
    78. 

  78. <code>make</code>.
    79. 

  79. The file has some definitions like paths to the external libraries,
    80. 

  80. compiler options and the like.
    81. 

  81. </p>
    82. 

  82. 

  83. <p>On Windows, the C runtime used to compile LuaFileSystem must be the same
    84. 

  84. runtime that Lua uses, or some LuaFileSystem functions will not work.</p>
    85. 

  85. 

  86. <h2><a name="installation"></a>Installation</h2>
    87. 

  87. 

  88. <p>The easiest way to install LuaFileSystem is to use LuaRocks:</p>
    89. 

  89. 

  90. <pre class="example">
    91. 

  91. luarocks install luafilesystem
    92. 

  92. </pre>
    93. 

  93. 

  94. <p>If you prefer to install LuaFileSystem manually, the compiled binary should be copied to a directory in your
    95. 

  95. <a href="http://www.lua.org/manual/5.1/manual.html#pdf-package.cpath">C path</a>.</p>
    96. 

  96. 

  97. <h2><a name="reference"></a>Reference</h2>
    98. 

  98. 

  99. <p>
    100. 

  100. LuaFileSystem offers the following functions:
    101. 

  101. </p>
    102. 

  102. 

  103. <dl class="reference">
    104. 

  104.     <dt><a name="attributes"></a><strong><code>lfs.attributes (filepath [, aname])</code></strong></dt>
    105. 

  105.     <dd>Returns a table with the file attributes corresponding to
    106. 

  106.     <code>filepath</code> (or <code>nil</code> followed by an error message
    107. 

  107.     in case of error).
    108. 

  108.     If the second optional argument is given, then only the value of the
    109. 

  109.     named attribute is returned (this use is equivalent to
    110. 

  110.     <code>lfs.attributes(filepath).aname</code>, but the table is not created
    111. 

  111.     and only one attribute is retrieved from the O.S.).
    112. 

  112.     The attributes are described as follows;
    113. 

  113.     attribute <code>mode</code> is a string, all the others are numbers,
    114. 

  114.     and the time related attributes use the same time reference of
    115. 

  115.     <a href="http://www.lua.org/manual/5.1/manual.html#pdf-os.time"><code>os.time</code></a>: 
    116. 

  116.         <dl>
    117. 

  117.         <dt><strong><code>dev</code></strong></dt>
    118. 

  118.         <dd>on Unix systems, this represents the device that the inode resides on. On Windows systems,
    119. 

  119.         represents the drive number of the disk containing the file</dd>
    120. 

  120.         
    121. 

  121.         <dt><strong><code>ino</code></strong></dt>
    122. 

  122.         <dd>on Unix systems, this represents the inode number. On Windows systems this has no meaning</dd>
    123. 

  123.         
    124. 

  124.         <dt><strong><code>mode</code></strong></dt>
    125. 

  125.         <dd>string representing the associated protection mode (the values could be
    126. 

  126.         <code>file</code>, <code>directory</code>, <code>link</code>, <code>socket</code>,
    127. 

  127.         <code>named pipe</code>, <code>char device</code>, <code>block device</code> or
    128. 

  128.         <code>other</code>)</dd>
    129. 

  129.         
    130. 

  130.         <dt><strong><code>nlink</code></strong></dt>
    131. 

  131. 		<dd>number of hard links to the file</dd>
    132. 

  132. 

  133.         <dt><strong><code>uid</code></strong></dt>
    134. 

  134. 		<dd>user-id of owner (Unix only, always 0 on Windows)</dd>
    135. 

  135. 

  136.         <dt><strong><code>gid</code></strong></dt>
    137. 

  137. 		<dd>group-id of owner (Unix only, always 0 on Windows)</dd>
    138. 

  138. 

  139.         <dt><strong><code>rdev</code></strong></dt>
    140. 

  140. 		<dd>on Unix systems, represents the device type, for special file inodes.
    141. 

  141.         On Windows systems represents the same as <code>dev</code></dd>
    142. 

  142. 

  143.         <dt><strong><code>access</code></strong></dt>
    144. 

  144. 		<dd>time of last access</dd>
    145. 

  145. 

  146.         <dt><strong><code>modification</code></strong></dt>
    147. 

  147. 		<dd>time of last data modification</dd>
    148. 

  148. 

  149.         <dt><strong><code>change</code></strong></dt>
    150. 

  150. 		<dd>time of last file status change</dd>
    151. 

  151. 

  152.         <dt><strong><code>size</code></strong></dt>
    153. 

  153. 		<dd>file size, in bytes</dd>
    154. 

  154. 

  155.         <dt><strong><code>blocks</code></strong></dt>
    156. 

  156. 		<dd>block allocated for file; (Unix only)</dd>
    157. 

  157.         
    158. 

  158.         <dt><strong><code>blksize</code></strong></dt>
    159. 

  159. 		<dd>optimal file system I/O blocksize; (Unix only)</dd>
    160. 

  160. 	    </dl>
    161. 

  161.     This function uses <code>stat</code> internally thus if the given
    162. 

  162.     <code>filepath</code> is a symbolic link, it is followed (if it points to
    163. 

  163.     another link the chain is followed recursively) and the information
    164. 

  164.     is about the file it refers to.
    165. 

  165.     To obtain information about the link itself, see function
    166. 

  166.     <a href="#symlinkattributes">lfs.symlinkattributes</a>.
    167. 

  167. 	</dd>
    168. 

  168. 

  169.     <dt><a name="chdir"></a><strong><code>lfs.chdir (path)</code></strong></dt>
    170. 

  170.     <dd>Changes the current working directory to the given
    171. 

  171.     <code>path</code>.<br />
    172. 

  172.     Returns <code>true</code> in case of success or <code>nil</code> plus an
    173. 

  173.     error string.</dd>
    174. 

  174. 

  175.     <dt><a name="chdir"></a><strong><code>lfs.lock_dir(path, [seconds_stale])</code></strong></dt>
    176. 

  176.     <dd>Creates a lockfile (called lockfile.lfs) in <code>path</code> if it does not
    177. 

  177.   exist and returns the lock. If the lock already exists checks it
    178. 

  178.   it's stale, using the second parameter (default for the second
    179. 

  179.   parameter is <code>INT_MAX</code>, which in practice means the lock will never
    180. 

  180.   be stale. To free the the lock call <code>lock:free()</code>. <br/>
    181. 

  181.    In case of any errors it returns nil and the error message. In
    182. 

  182.   particular, if the lock exists and is not stale it returns the
    183. 

  183.   "File exists" message.</dd>
    184. 

  184.         
    185. 

  185.     <dt><a name="getcwd"></a><strong><code>lfs.currentdir ()</code></strong></dt>
    186. 

  186.     <dd>Returns a string with the current working directory or <code>nil</code>
    187. 

  187.     plus an error string.</dd>
    188. 

  188.     
    189. 

  189.     <dt><a name="dir"></a><strong><code>iter, dir_obj = lfs.dir (path)</code></strong></dt>
    190. 

  190.     <dd>
    191. 

  191.     Lua iterator over the entries of a given directory.
    192. 

  192.     Each time the iterator is called with <code>dir_obj</code> it returns a directory entry's name as a string, or
    193. 

  193.     <code>nil</code> if there are no more entries. You can also iterate by calling <code>dir_obj:next()</code>, and
    194. 

  194.     explicitly close the directory before the iteration finished with <code>dir_obj:close()</code>.
    195. 

  195.     Raises an error if <code>path</code> is not a directory.
    196. 

  196.     </dd>
    197. 

  197.     
    198. 

  198.     <dt><a name="lock"></a><strong><code>lfs.lock (filehandle, mode[, start[, length]])</code></strong></dt>
    199. 

  199.     <dd>Locks a file or a part of it. This function works on <em>open files</em>; the
    200. 

  200.     file handle should be specified as the first argument.
    201. 

  201.     The string <code>mode</code> could be either
    202. 

  202.     <code>r</code> (for a read/shared lock) or <code>w</code> (for a
    203. 

  203.     write/exclusive lock). The optional arguments <code>start</code>
    204. 

  204.     and <code>length</code> can be used to specify a starting point and
    205. 

  205.     its length; both should be numbers.<br />
    206. 

  206.     Returns <code>true</code> if the operation was successful; in
    207. 

  207.     case of error, it returns <code>nil</code> plus an error string.
    208. 

  208.     </dd>
    209. 

  209.     
    210. 

  210.     <dt><a name="mkdir"></a><strong><code>lfs.mkdir (dirname)</code></strong></dt>
    211. 

  211.     <dd>Creates a new directory. The argument is the name of the new
    212. 

  212.     directory.<br />
    213. 

  213.     Returns <code>true</code> if the operation was successful;
    214. 

  214.     in case of error, it returns <code>nil</code> plus an error string.
    215. 

  215.     </dd>
    216. 

  216.     
    217. 

  217.     <dt><a name="rmdir"></a><strong><code>lfs.rmdir (dirname)</code></strong></dt>
    218. 

  218.     <dd>Removes an existing directory. The argument is the name of the directory.<br />
    219. 

  219.     Returns <code>true</code> if the operation was successful;
    220. 

  220.     in case of error, it returns <code>nil</code> plus an error string.</dd>
    221. 

  221. 

  222.     <dt><a name="setmode"></a><strong><code>lfs.setmode (file, mode)</code></strong></dt>
    223. 

  223.     <dd>Sets the writing mode for a file. The mode string can be either <code>binary</code> or <code>text</code>.
    224. 

  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. 

  225.     <code>lfs.setmode</code> exists before using it.
    226. 

  226.     </dd>
    227. 

  227.     
    228. 

  228.     <dt><a name="symlinkattributes"></a><strong><code>lfs.symlinkattributes (filepath [, aname])</code></strong></dt>
    229. 

  229.     <dd>Identical to <a href="#attributes">lfs.attributes</a> except that
    230. 

  230.     it obtains information about the link itself (not the file it refers to).
    231. 

  231.     This function is not available in Windows so you may want to make sure that
    232. 

  232.     <code>lfs.symlinkattributes</code> exists before using it.
    233. 

  233.     </dd>
    234. 

  234. 

  235.     <dt><a name="touch"></a><strong><code>lfs.touch (filepath [, atime [, mtime]])</code></strong></dt>
    236. 

  236.     <dd>Set access and modification times of a file. This function is
    237. 

  237.     a bind to <code>utime</code> function. The first argument is the
    238. 

  238.     filename, the second argument (<code>atime</code>) is the access time,
    239. 

  239.     and the third argument (<code>mtime</code>) is the modification time.
    240. 

  240.     Both times are provided in seconds (which should be generated with
    241. 

  241.     Lua standard function <code>os.time</code>).
    242. 

  242.     If the modification time is omitted, the access time provided is used;
    243. 

  243.     if both times are omitted, the current time is used.<br />
    244. 

  244.     Returns <code>true</code> if the operation was successful;
    245. 

  245.     in case of error, it returns <code>nil</code> plus an error string.
    246. 

  246.     </dd>
    247. 

  247.     
    248. 

  248.     <dt><a name="unlock"></a><strong><code>lfs.unlock (filehandle[, start[, length]])</code></strong></dt>
    249. 

  249.     <dd>Unlocks a file or a part of it. This function works on
    250. 

  250.     <em>open files</em>; the file handle should be specified as the first
    251. 

  251.     argument. The optional arguments <code>start</code> and
    252. 

  252.     <code>length</code> can be used to specify a starting point and its
    253. 

  253.     length; both should be numbers.<br />
    254. 

  254.     Returns <code>true</code> if the operation was successful;
    255. 

  255.     in case of error, it returns <code>nil</code> plus an error string.
    256. 

  256.     </dd>
    257. 

  257. </dl>
    258. 

  258. 

  259. </div> <!-- id="content" -->
    260. 

  260. 

  261. </div> <!-- id="main" -->
    262. 

  262. 

  263. <div id="about">
    264. 

  264. 	<p><a href="http://validator.w3.org/check?uri=referer">Valid XHTML 1.0!</a></p>
    265. 

  265. 	<p><small>$Id: manual.html,v 1.45 2009/06/03 20:53:55 mascarenhas Exp $</small></p>
    266. 

  266. </div> <!-- id="about" -->
    267. 

  267. 

  268. </div> <!-- id="container" -->
    269. 

  269. 

  270. </body>
    271. 

  271. </html>
    272.