nixio.File.html 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
  2. "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
  3. <html>
  4. <head>
  5. <title>Reference</title>
  6. <link rel="stylesheet" href="../luadoc.css" type="text/css" />
  7. <!--meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/-->
  8. </head>
  9. <body>
  10. <div id="container">
  11. <div id="product">
  12. <div id="product_logo"></div>
  13. <div id="product_name"><big><b></b></big></div>
  14. <div id="product_description"></div>
  15. </div> <!-- id="product" -->
  16. <div id="main">
  17. <div id="navigation">
  18. <h1>LuaDoc</h1>
  19. <ul>
  20. <li><a href="../index.html">Index</a></li>
  21. </ul>
  22. <!-- Module list -->
  23. <h1>Modules</h1>
  24. <ul>
  25. <li>
  26. <a href="../modules/luci.dispatcher.html">luci.dispatcher</a>
  27. </li>
  28. <li>
  29. <a href="../modules/luci.http.html">luci.http</a>
  30. </li>
  31. <li>
  32. <a href="../modules/luci.http.protocol.html">luci.http.protocol</a>
  33. </li>
  34. <li>
  35. <a href="../modules/luci.http.protocol.conditionals.html">luci.http.protocol.conditionals</a>
  36. </li>
  37. <li>
  38. <a href="../modules/luci.http.protocol.date.html">luci.http.protocol.date</a>
  39. </li>
  40. <li>
  41. <a href="../modules/luci.http.protocol.mime.html">luci.http.protocol.mime</a>
  42. </li>
  43. <li>
  44. <a href="../modules/luci.i18n.html">luci.i18n</a>
  45. </li>
  46. <li>
  47. <a href="../modules/luci.ip.html">luci.ip</a>
  48. </li>
  49. <li>
  50. <a href="../modules/luci.ip.cidr.html">luci.ip.cidr</a>
  51. </li>
  52. <li>
  53. <a href="../modules/luci.json.html">luci.json</a>
  54. </li>
  55. <li>
  56. <a href="../modules/luci.jsonc.html">luci.jsonc</a>
  57. </li>
  58. <li>
  59. <a href="../modules/luci.jsonc.parser.html">luci.jsonc.parser</a>
  60. </li>
  61. <li>
  62. <a href="../modules/luci.model.ipkg.html">luci.model.ipkg</a>
  63. </li>
  64. <li>
  65. <a href="../modules/luci.model.uci.html">luci.model.uci</a>
  66. </li>
  67. <li>
  68. <a href="../modules/luci.rpcc.html">luci.rpcc</a>
  69. </li>
  70. <li>
  71. <a href="../modules/luci.rpcc.ruci.html">luci.rpcc.ruci</a>
  72. </li>
  73. <li>
  74. <a href="../modules/luci.sys.html">luci.sys</a>
  75. </li>
  76. <li>
  77. <a href="../modules/luci.sys.init.html">luci.sys.init</a>
  78. </li>
  79. <li>
  80. <a href="../modules/luci.sys.iptparser.html">luci.sys.iptparser</a>
  81. </li>
  82. <li>
  83. <a href="../modules/luci.sys.net.html">luci.sys.net</a>
  84. </li>
  85. <li>
  86. <a href="../modules/luci.sys.process.html">luci.sys.process</a>
  87. </li>
  88. <li>
  89. <a href="../modules/luci.sys.user.html">luci.sys.user</a>
  90. </li>
  91. <li>
  92. <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
  93. </li>
  94. <li>
  95. <a href="../modules/luci.util.html">luci.util</a>
  96. </li>
  97. <li>
  98. <a href="../modules/nixio.html">nixio</a>
  99. </li>
  100. <li>
  101. <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
  102. </li>
  103. <li>
  104. <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
  105. </li>
  106. <li><strong>nixio.File</strong></li>
  107. <li>
  108. <a href="../modules/nixio.README.html">nixio.README</a>
  109. </li>
  110. <li>
  111. <a href="../modules/nixio.Socket.html">nixio.Socket</a>
  112. </li>
  113. <li>
  114. <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
  115. </li>
  116. <li>
  117. <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
  118. </li>
  119. <li>
  120. <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
  121. </li>
  122. <li>
  123. <a href="../modules/nixio.bin.html">nixio.bin</a>
  124. </li>
  125. <li>
  126. <a href="../modules/nixio.bit.html">nixio.bit</a>
  127. </li>
  128. <li>
  129. <a href="../modules/nixio.crypto.html">nixio.crypto</a>
  130. </li>
  131. <li>
  132. <a href="../modules/nixio.fs.html">nixio.fs</a>
  133. </li>
  134. </ul>
  135. <!-- File list -->
  136. </div><!-- id="navigation" -->
  137. <div id="content">
  138. <h1>Object Instance <code>nixio.File</code></h1>
  139. <p>
  140. Large File Object.
  141. Large file operations are supported up to 52 bits if the Lua number type is
  142. double (default).</p>
  143. <h2>Functions</h2>
  144. <table class="function_list">
  145. <tr>
  146. <td class="name" nowrap><a href="#File.close">File:close</a>&nbsp;()</td>
  147. <td class="summary">
  148. Close the file descriptor.</td>
  149. </tr>
  150. <tr>
  151. <td class="name" nowrap><a href="#File.fileno">File:fileno</a>&nbsp;()</td>
  152. <td class="summary">
  153. Get the number of the filedescriptor.</td>
  154. </tr>
  155. <tr>
  156. <td class="name" nowrap><a href="#File.lock">File:lock</a>&nbsp;(command, length)</td>
  157. <td class="summary">
  158. Apply or test a lock on the file.</td>
  159. </tr>
  160. <tr>
  161. <td class="name" nowrap><a href="#File.read">File:read</a>&nbsp;(length)</td>
  162. <td class="summary">
  163. Read from a file descriptor.</td>
  164. </tr>
  165. <tr>
  166. <td class="name" nowrap><a href="#File.seek">File:seek</a>&nbsp;(offset, whence)</td>
  167. <td class="summary">
  168. Reposition read / write offset of the file descriptor.</td>
  169. </tr>
  170. <tr>
  171. <td class="name" nowrap><a href="#File.setblocking">File:setblocking</a>&nbsp;(blocking)</td>
  172. <td class="summary">
  173. (POSIX) Set the blocking mode of the file descriptor.</td>
  174. </tr>
  175. <tr>
  176. <td class="name" nowrap><a href="#File.stat">File:stat</a>&nbsp;(field)</td>
  177. <td class="summary">
  178. Get file status and attributes.</td>
  179. </tr>
  180. <tr>
  181. <td class="name" nowrap><a href="#File.sync">File:sync</a>&nbsp;(data_only)</td>
  182. <td class="summary">
  183. Synchronizes the file with the storage device.</td>
  184. </tr>
  185. <tr>
  186. <td class="name" nowrap><a href="#File.tell">File:tell</a>&nbsp;()</td>
  187. <td class="summary">
  188. Return the current read / write offset of the file descriptor.</td>
  189. </tr>
  190. <tr>
  191. <td class="name" nowrap><a href="#File.write">File:write</a>&nbsp;(buffer, offset, length)</td>
  192. <td class="summary">
  193. Write to the file descriptor.</td>
  194. </tr>
  195. </table>
  196. <br/>
  197. <br/>
  198. <h2><a name="functions"></a>Functions</h2>
  199. <dl class="function">
  200. <dt><a name="File.close"></a><strong>File:close</strong>&nbsp;()</dt>
  201. <dd>
  202. Close the file descriptor.
  203. <h3>Return value:</h3>
  204. true
  205. </dd>
  206. <dt><a name="File.fileno"></a><strong>File:fileno</strong>&nbsp;()</dt>
  207. <dd>
  208. Get the number of the filedescriptor.
  209. <h3>Return value:</h3>
  210. file descriptor number
  211. </dd>
  212. <dt><a name="File.lock"></a><strong>File:lock</strong>&nbsp;(command, length)</dt>
  213. <dd>
  214. Apply or test a lock on the file.
  215. <h3>Parameters</h3>
  216. <ul>
  217. <li>
  218. command: Locking Command ["lock", "tlock", "ulock", "test"]
  219. </li>
  220. <li>
  221. length: Amount of Bytes to lock from current offset (optional)
  222. </li>
  223. </ul>
  224. <h3>Usage</h3>
  225. <ul>
  226. <li>This function calls lockf() on POSIX and _locking() on Windows.
  227. <li>The "lock" command is blocking, "tlock" is non-blocking,
  228. "ulock" unlocks and "test" only tests for the lock.
  229. <li>The "test" command is not available on Windows.
  230. <li>Locks are by default advisory on POSIX, but mandatory on Windows.
  231. </ul>
  232. <h3>Return value:</h3>
  233. true
  234. </dd>
  235. <dt><a name="File.read"></a><strong>File:read</strong>&nbsp;(length)</dt>
  236. <dd>
  237. Read from a file descriptor.
  238. <h3>Parameters</h3>
  239. <ul>
  240. <li>
  241. length: Amount of data to read (in Bytes).
  242. </li>
  243. </ul>
  244. <h3>Usage</h3>
  245. <ul>
  246. <li><strong>Warning:</strong> It is not guaranteed that all requested data
  247. is read at once especially when dealing with pipes.
  248. You have to check the return value - the length of the buffer actually read -
  249. or use the safe IO functions in the high-level IO utility module.
  250. <li>The length of the return buffer is limited by the (compile time)
  251. nixio buffersize which is <em>nixio.const.buffersize</em> (8192 by default).
  252. Any read request greater than that will be safely truncated to this value.
  253. </ul>
  254. <h3>Return value:</h3>
  255. buffer containing data successfully read
  256. </dd>
  257. <dt><a name="File.seek"></a><strong>File:seek</strong>&nbsp;(offset, whence)</dt>
  258. <dd>
  259. Reposition read / write offset of the file descriptor.
  260. The seek will be done either from the beginning of the file or relative
  261. to the current position or relative to the end.
  262. <h3>Parameters</h3>
  263. <ul>
  264. <li>
  265. offset: File Offset
  266. </li>
  267. <li>
  268. whence: Starting point [<strong>"set"</strong>, "cur", "end"]
  269. </li>
  270. </ul>
  271. <h3>Usage:</h3>
  272. This function calls lseek().
  273. <h3>Return value:</h3>
  274. new (absolute) offset position
  275. </dd>
  276. <dt><a name="File.setblocking"></a><strong>File:setblocking</strong>&nbsp;(blocking)</dt>
  277. <dd>
  278. (POSIX) Set the blocking mode of the file descriptor.
  279. <h3>Parameters</h3>
  280. <ul>
  281. <li>
  282. blocking: (boolean)
  283. </li>
  284. </ul>
  285. <h3>Return value:</h3>
  286. true
  287. </dd>
  288. <dt><a name="File.stat"></a><strong>File:stat</strong>&nbsp;(field)</dt>
  289. <dd>
  290. Get file status and attributes.
  291. <h3>Parameters</h3>
  292. <ul>
  293. <li>
  294. field: Only return a specific field, not the whole table (optional)
  295. </li>
  296. </ul>
  297. <h3>Usage:</h3>
  298. This function calls fstat().
  299. <h3>Return value:</h3>
  300. Table containing: <ul>
  301. <li>atime = Last access timestamp</li>
  302. <li>blksize = Blocksize (POSIX only)</li>
  303. <li>blocks = Blocks used (POSIX only)</li>
  304. <li>ctime = Creation timestamp</li>
  305. <li>dev = Device ID</li>
  306. <li>gid = Group ID</li>
  307. <li>ino = Inode</li>
  308. <li>modedec = Mode converted into a decimal number</li>
  309. <li>modestr = Mode as string as returned by <code>ls -l</code></li>
  310. <li>mtime = Last modification timestamp</li>
  311. <li>nlink = Number of links</li>
  312. <li>rdev = Device ID (if special file)</li>
  313. <li>size = Size in bytes</li>
  314. <li>type = ["reg", "dir", "chr", "blk", "fifo", "lnk", "sock"]</li>
  315. <li>uid = User ID</li>
  316. </ul>
  317. </dd>
  318. <dt><a name="File.sync"></a><strong>File:sync</strong>&nbsp;(data_only)</dt>
  319. <dd>
  320. Synchronizes the file with the storage device.
  321. Returns when the file is successfully written to the disk.
  322. <h3>Parameters</h3>
  323. <ul>
  324. <li>
  325. data_only: Do not synchronize the metadata. (optional, boolean)
  326. </li>
  327. </ul>
  328. <h3>Usage</h3>
  329. <ul>
  330. <li>This function calls fsync() when data_only equals false
  331. otherwise fdatasync(), on Windows _commit() is used instead.
  332. <li>fdatasync() is only supported by Linux and Solaris. For other systems
  333. the <em>data_only</em> parameter is ignored and fsync() is always called.
  334. </ul>
  335. <h3>Return value:</h3>
  336. true
  337. </dd>
  338. <dt><a name="File.tell"></a><strong>File:tell</strong>&nbsp;()</dt>
  339. <dd>
  340. Return the current read / write offset of the file descriptor.
  341. <h3>Usage:</h3>
  342. This function calls lseek() with offset 0 from the current position.
  343. <h3>Return value:</h3>
  344. offset position
  345. </dd>
  346. <dt><a name="File.write"></a><strong>File:write</strong>&nbsp;(buffer, offset, length)</dt>
  347. <dd>
  348. Write to the file descriptor.
  349. <h3>Parameters</h3>
  350. <ul>
  351. <li>
  352. buffer: Buffer holding the data to be written.
  353. </li>
  354. <li>
  355. offset: Offset to start reading the buffer from. (optional)
  356. </li>
  357. <li>
  358. length: Length of chunk to read from the buffer. (optional)
  359. </li>
  360. </ul>
  361. <h3>Usage</h3>
  362. <ul>
  363. <li><strong>Warning:</strong> It is not guaranteed that all data
  364. in the buffer is written at once especially when dealing with pipes.
  365. You have to check the return value - the number of bytes actually written -
  366. or use the safe IO functions in the high-level IO utility module.
  367. <li>Unlike standard Lua indexing the lowest offset and default is 0.
  368. </ul>
  369. <h3>Return value:</h3>
  370. number of bytes written
  371. </dd>
  372. </dl>
  373. </div> <!-- id="content" -->
  374. </div> <!-- id="main" -->
  375. <div id="about">
  376. <p><a href="http://validator.w3.org/check?uri=referer"><img src="http://www.w3.org/Icons/valid-xhtml10" alt="Valid XHTML 1.0!" height="31" width="88" /></a></p>
  377. </div> <!-- id="about" -->
  378. </div> <!-- id="container" -->
  379. </body>
  380. </html>