1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
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"/-->
14 <div id="product_logo"></div>
15 <div id="product_name"><big><b></b></big></div>
16 <div id="product_description"></div>
17 </div> <!-- id="product" -->
27 <li><a href="../index.html">Index</a></li>
38 <a href="../modules/luci.dispatcher.html">luci.dispatcher</a>
42 <a href="../modules/luci.http.protocol.html">luci.http.protocol</a>
46 <a href="../modules/luci.http.protocol.conditionals.html">luci.http.protocol.conditionals</a>
50 <a href="../modules/luci.http.protocol.date.html">luci.http.protocol.date</a>
54 <a href="../modules/luci.http.protocol.mime.html">luci.http.protocol.mime</a>
58 <a href="../modules/luci.i18n.html">luci.i18n</a>
62 <a href="../modules/luci.ip.html">luci.ip</a>
66 <a href="../modules/luci.ip.cidr.html">luci.ip.cidr</a>
70 <a href="../modules/luci.jsonc.html">luci.jsonc</a>
74 <a href="../modules/luci.jsonc.parser.html">luci.jsonc.parser</a>
78 <a href="../modules/luci.sys.init.html">luci.sys.init</a>
82 <a href="../modules/luci.sys.iptparser.html">luci.sys.iptparser</a>
86 <a href="../modules/luci.sys.net.html">luci.sys.net</a>
90 <a href="../modules/luci.sys.process.html">luci.sys.process</a>
94 <a href="../modules/luci.sys.user.html">luci.sys.user</a>
98 <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
102 <a href="../modules/nixio.html">nixio</a>
106 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
110 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
113 <li><strong>nixio.File</strong></li>
116 <a href="../modules/nixio.README.html">nixio.README</a>
120 <a href="../modules/nixio.Socket.html">nixio.Socket</a>
124 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
128 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
132 <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
136 <a href="../modules/nixio.bin.html">nixio.bin</a>
140 <a href="../modules/nixio.bit.html">nixio.bit</a>
144 <a href="../modules/nixio.crypto.html">nixio.crypto</a>
148 <a href="../modules/nixio.fs.html">nixio.fs</a>
163 </div><!-- id="navigation" -->
167 <h1>Object Instance <code>nixio.File</code></h1>
171 Large file operations are supported up to 52 bits if the Lua number type is
172 double (default).</p>
181 <table class="function_list">
184 <td class="name" nowrap><a href="#File.close">File:close</a> ()</td>
186 Close the file descriptor.</td>
190 <td class="name" nowrap><a href="#File.fileno">File:fileno</a> ()</td>
192 Get the number of the filedescriptor.</td>
196 <td class="name" nowrap><a href="#File.lock">File:lock</a> (command, length)</td>
198 Apply or test a lock on the file.</td>
202 <td class="name" nowrap><a href="#File.read">File:read</a> (length)</td>
204 Read from a file descriptor.</td>
208 <td class="name" nowrap><a href="#File.seek">File:seek</a> (offset, whence)</td>
210 Reposition read / write offset of the file descriptor.</td>
214 <td class="name" nowrap><a href="#File.setblocking">File:setblocking</a> (blocking)</td>
216 (POSIX) Set the blocking mode of the file descriptor.</td>
220 <td class="name" nowrap><a href="#File.stat">File:stat</a> (field)</td>
222 Get file status and attributes.</td>
226 <td class="name" nowrap><a href="#File.sync">File:sync</a> (data_only)</td>
228 Synchronizes the file with the storage device.</td>
232 <td class="name" nowrap><a href="#File.tell">File:tell</a> ()</td>
234 Return the current read / write offset of the file descriptor.</td>
238 <td class="name" nowrap><a href="#File.write">File:write</a> (buffer, offset, length)</td>
240 Write to the file descriptor.</td>
254 <h2><a name="functions"></a>Functions</h2>
255 <dl class="function">
259 <dt><a name="File.close"></a><strong>File:close</strong> ()</dt>
262 Close the file descriptor.
270 <h3>Return value:</h3>
280 <dt><a name="File.fileno"></a><strong>File:fileno</strong> ()</dt>
283 Get the number of the filedescriptor.
291 <h3>Return value:</h3>
292 file descriptor number
301 <dt><a name="File.lock"></a><strong>File:lock</strong> (command, length)</dt>
304 Apply or test a lock on the file.
311 command: Locking Command ["lock", "tlock", "ulock", "test"]
315 length: Amount of Bytes to lock from current offset (optional)
326 <li>This function calls lockf() on POSIX and _locking() on Windows.
328 <li>The "lock" command is blocking, "tlock" is non-blocking,
329 "ulock" unlocks and "test" only tests for the lock.
331 <li>The "test" command is not available on Windows.
333 <li>Locks are by default advisory on POSIX, but mandatory on Windows.
339 <h3>Return value:</h3>
349 <dt><a name="File.read"></a><strong>File:read</strong> (length)</dt>
352 Read from a file descriptor.
359 length: Amount of data to read (in Bytes).
370 <li><strong>Warning:</strong> It is not guaranteed that all requested data
371 is read at once especially when dealing with pipes.
372 You have to check the return value - the length of the buffer actually read -
373 or use the safe IO functions in the high-level IO utility module.
375 <li>The length of the return buffer is limited by the (compile time)
376 nixio buffersize which is <em>nixio.const.buffersize</em> (8192 by default).
377 Any read request greater than that will be safely truncated to this value.
383 <h3>Return value:</h3>
384 buffer containing data successfully read
393 <dt><a name="File.seek"></a><strong>File:seek</strong> (offset, whence)</dt>
396 Reposition read / write offset of the file descriptor.
397 The seek will be done either from the beginning of the file or relative
398 to the current position or relative to the end.
409 whence: Starting point [<strong>"set"</strong>, "cur", "end"]
418 This function calls lseek().
422 <h3>Return value:</h3>
423 new (absolute) offset position
432 <dt><a name="File.setblocking"></a><strong>File:setblocking</strong> (blocking)</dt>
435 (POSIX) Set the blocking mode of the file descriptor.
452 <h3>Return value:</h3>
462 <dt><a name="File.stat"></a><strong>File:stat</strong> (field)</dt>
465 Get file status and attributes.
472 field: Only return a specific field, not the whole table (optional)
481 This function calls fstat().
485 <h3>Return value:</h3>
486 Table containing: <ul>
487 <li>atime = Last access timestamp</li>
488 <li>blksize = Blocksize (POSIX only)</li>
489 <li>blocks = Blocks used (POSIX only)</li>
490 <li>ctime = Creation timestamp</li>
491 <li>dev = Device ID</li>
492 <li>gid = Group ID</li>
494 <li>modedec = Mode converted into a decimal number</li>
495 <li>modestr = Mode as string as returned by <code>ls -l</code></li>
496 <li>mtime = Last modification timestamp</li>
497 <li>nlink = Number of links</li>
498 <li>rdev = Device ID (if special file)</li>
499 <li>size = Size in bytes</li>
500 <li>type = ["reg", "dir", "chr", "blk", "fifo", "lnk", "sock"]</li>
501 <li>uid = User ID</li>
511 <dt><a name="File.sync"></a><strong>File:sync</strong> (data_only)</dt>
514 Synchronizes the file with the storage device.
515 Returns when the file is successfully written to the disk.
522 data_only: Do not synchronize the metadata. (optional, boolean)
533 <li>This function calls fsync() when data_only equals false
534 otherwise fdatasync(), on Windows _commit() is used instead.
536 <li>fdatasync() is only supported by Linux and Solaris. For other systems
537 the <em>data_only</em> parameter is ignored and fsync() is always called.
543 <h3>Return value:</h3>
553 <dt><a name="File.tell"></a><strong>File:tell</strong> ()</dt>
556 Return the current read / write offset of the file descriptor.
563 This function calls lseek() with offset 0 from the current position.
567 <h3>Return value:</h3>
577 <dt><a name="File.write"></a><strong>File:write</strong> (buffer, offset, length)</dt>
580 Write to the file descriptor.
587 buffer: Buffer holding the data to be written.
591 offset: Offset to start reading the buffer from. (optional)
595 length: Length of chunk to read from the buffer. (optional)
606 <li><strong>Warning:</strong> It is not guaranteed that all data
607 in the buffer is written at once especially when dealing with pipes.
608 You have to check the return value - the number of bytes actually written -
609 or use the safe IO functions in the high-level IO utility module.
611 <li>Unlike standard Lua indexing the lowest offset and default is 0.
617 <h3>Return value:</h3>
618 number of bytes written
631 </div> <!-- id="content" -->
633 </div> <!-- id="main" -->
636 <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>
637 </div> <!-- id="about" -->
639 </div> <!-- id="container" -->