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.html">luci.http</a>
46 <a href="../modules/luci.http.protocol.html">luci.http.protocol</a>
50 <a href="../modules/luci.http.protocol.conditionals.html">luci.http.protocol.conditionals</a>
54 <a href="../modules/luci.http.protocol.date.html">luci.http.protocol.date</a>
58 <a href="../modules/luci.http.protocol.mime.html">luci.http.protocol.mime</a>
62 <a href="../modules/luci.i18n.html">luci.i18n</a>
66 <a href="../modules/luci.ip.html">luci.ip</a>
70 <a href="../modules/luci.ip.cidr.html">luci.ip.cidr</a>
74 <a href="../modules/luci.json.html">luci.json</a>
78 <a href="../modules/luci.jsonc.html">luci.jsonc</a>
82 <a href="../modules/luci.jsonc.parser.html">luci.jsonc.parser</a>
86 <a href="../modules/luci.model.ipkg.html">luci.model.ipkg</a>
90 <a href="../modules/luci.model.uci.html">luci.model.uci</a>
94 <a href="../modules/luci.rpcc.html">luci.rpcc</a>
98 <a href="../modules/luci.rpcc.ruci.html">luci.rpcc.ruci</a>
102 <a href="../modules/luci.sys.html">luci.sys</a>
106 <a href="../modules/luci.sys.init.html">luci.sys.init</a>
110 <a href="../modules/luci.sys.iptparser.html">luci.sys.iptparser</a>
114 <a href="../modules/luci.sys.net.html">luci.sys.net</a>
118 <a href="../modules/luci.sys.process.html">luci.sys.process</a>
122 <a href="../modules/luci.sys.user.html">luci.sys.user</a>
126 <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
130 <a href="../modules/luci.util.html">luci.util</a>
134 <a href="../modules/nixio.html">nixio</a>
138 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
142 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
145 <li><strong>nixio.File</strong></li>
148 <a href="../modules/nixio.README.html">nixio.README</a>
152 <a href="../modules/nixio.Socket.html">nixio.Socket</a>
156 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
160 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
164 <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
168 <a href="../modules/nixio.bin.html">nixio.bin</a>
172 <a href="../modules/nixio.bit.html">nixio.bit</a>
176 <a href="../modules/nixio.crypto.html">nixio.crypto</a>
180 <a href="../modules/nixio.fs.html">nixio.fs</a>
195 </div><!-- id="navigation" -->
199 <h1>Object Instance <code>nixio.File</code></h1>
203 Large file operations are supported up to 52 bits if the Lua number type is
204 double (default).</p>
213 <table class="function_list">
216 <td class="name" nowrap><a href="#File.close">File:close</a> ()</td>
218 Close the file descriptor.</td>
222 <td class="name" nowrap><a href="#File.fileno">File:fileno</a> ()</td>
224 Get the number of the filedescriptor.</td>
228 <td class="name" nowrap><a href="#File.lock">File:lock</a> (command, length)</td>
230 Apply or test a lock on the file.</td>
234 <td class="name" nowrap><a href="#File.read">File:read</a> (length)</td>
236 Read from a file descriptor.</td>
240 <td class="name" nowrap><a href="#File.seek">File:seek</a> (offset, whence)</td>
242 Reposition read / write offset of the file descriptor.</td>
246 <td class="name" nowrap><a href="#File.setblocking">File:setblocking</a> (blocking)</td>
248 (POSIX) Set the blocking mode of the file descriptor.</td>
252 <td class="name" nowrap><a href="#File.stat">File:stat</a> (field)</td>
254 Get file status and attributes.</td>
258 <td class="name" nowrap><a href="#File.sync">File:sync</a> (data_only)</td>
260 Synchronizes the file with the storage device.</td>
264 <td class="name" nowrap><a href="#File.tell">File:tell</a> ()</td>
266 Return the current read / write offset of the file descriptor.</td>
270 <td class="name" nowrap><a href="#File.write">File:write</a> (buffer, offset, length)</td>
272 Write to the file descriptor.</td>
286 <h2><a name="functions"></a>Functions</h2>
287 <dl class="function">
291 <dt><a name="File.close"></a><strong>File:close</strong> ()</dt>
294 Close the file descriptor.
302 <h3>Return value:</h3>
312 <dt><a name="File.fileno"></a><strong>File:fileno</strong> ()</dt>
315 Get the number of the filedescriptor.
323 <h3>Return value:</h3>
324 file descriptor number
333 <dt><a name="File.lock"></a><strong>File:lock</strong> (command, length)</dt>
336 Apply or test a lock on the file.
343 command: Locking Command ["lock", "tlock", "ulock", "test"]
347 length: Amount of Bytes to lock from current offset (optional)
358 <li>This function calls lockf() on POSIX and _locking() on Windows.
360 <li>The "lock" command is blocking, "tlock" is non-blocking,
361 "ulock" unlocks and "test" only tests for the lock.
363 <li>The "test" command is not available on Windows.
365 <li>Locks are by default advisory on POSIX, but mandatory on Windows.
371 <h3>Return value:</h3>
381 <dt><a name="File.read"></a><strong>File:read</strong> (length)</dt>
384 Read from a file descriptor.
391 length: Amount of data to read (in Bytes).
402 <li><strong>Warning:</strong> It is not guaranteed that all requested data
403 is read at once especially when dealing with pipes.
404 You have to check the return value - the length of the buffer actually read -
405 or use the safe IO functions in the high-level IO utility module.
407 <li>The length of the return buffer is limited by the (compile time)
408 nixio buffersize which is <em>nixio.const.buffersize</em> (8192 by default).
409 Any read request greater than that will be safely truncated to this value.
415 <h3>Return value:</h3>
416 buffer containing data successfully read
425 <dt><a name="File.seek"></a><strong>File:seek</strong> (offset, whence)</dt>
428 Reposition read / write offset of the file descriptor.
429 The seek will be done either from the beginning of the file or relative
430 to the current position or relative to the end.
441 whence: Starting point [<strong>"set"</strong>, "cur", "end"]
450 This function calls lseek().
454 <h3>Return value:</h3>
455 new (absolute) offset position
464 <dt><a name="File.setblocking"></a><strong>File:setblocking</strong> (blocking)</dt>
467 (POSIX) Set the blocking mode of the file descriptor.
484 <h3>Return value:</h3>
494 <dt><a name="File.stat"></a><strong>File:stat</strong> (field)</dt>
497 Get file status and attributes.
504 field: Only return a specific field, not the whole table (optional)
513 This function calls fstat().
517 <h3>Return value:</h3>
518 Table containing: <ul>
519 <li>atime = Last access timestamp</li>
520 <li>blksize = Blocksize (POSIX only)</li>
521 <li>blocks = Blocks used (POSIX only)</li>
522 <li>ctime = Creation timestamp</li>
523 <li>dev = Device ID</li>
524 <li>gid = Group ID</li>
526 <li>modedec = Mode converted into a decimal number</li>
527 <li>modestr = Mode as string as returned by <code>ls -l</code></li>
528 <li>mtime = Last modification timestamp</li>
529 <li>nlink = Number of links</li>
530 <li>rdev = Device ID (if special file)</li>
531 <li>size = Size in bytes</li>
532 <li>type = ["reg", "dir", "chr", "blk", "fifo", "lnk", "sock"]</li>
533 <li>uid = User ID</li>
543 <dt><a name="File.sync"></a><strong>File:sync</strong> (data_only)</dt>
546 Synchronizes the file with the storage device.
547 Returns when the file is successfully written to the disk.
554 data_only: Do not synchronize the metadata. (optional, boolean)
565 <li>This function calls fsync() when data_only equals false
566 otherwise fdatasync(), on Windows _commit() is used instead.
568 <li>fdatasync() is only supported by Linux and Solaris. For other systems
569 the <em>data_only</em> parameter is ignored and fsync() is always called.
575 <h3>Return value:</h3>
585 <dt><a name="File.tell"></a><strong>File:tell</strong> ()</dt>
588 Return the current read / write offset of the file descriptor.
595 This function calls lseek() with offset 0 from the current position.
599 <h3>Return value:</h3>
609 <dt><a name="File.write"></a><strong>File:write</strong> (buffer, offset, length)</dt>
612 Write to the file descriptor.
619 buffer: Buffer holding the data to be written.
623 offset: Offset to start reading the buffer from. (optional)
627 length: Length of chunk to read from the buffer. (optional)
638 <li><strong>Warning:</strong> It is not guaranteed that all data
639 in the buffer is written at once especially when dealing with pipes.
640 You have to check the return value - the number of bytes actually written -
641 or use the safe IO functions in the high-level IO utility module.
643 <li>Unlike standard Lua indexing the lowest offset and default is 0.
649 <h3>Return value:</h3>
650 number of bytes written
663 </div> <!-- id="content" -->
665 </div> <!-- id="main" -->
668 <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>
669 </div> <!-- id="about" -->
671 </div> <!-- id="container" -->