doc/modules/nixio.File.html

   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
  10 <body>
  11 <div id="container">
  12
  13 <div id="product">
  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" -->
  18
  19 <div id="main">
  20
  21 <div id="navigation">
  22
  23
  24 <h1>LuaDoc</h1>
  25 <ul>
  26
  27         <li><a href="../index.html">Index</a></li>
  28
  29 </ul>
  30
  31
  32 <!-- Module list -->
  33
  34 <h1>Modules</h1>
  35 <ul>
  36
  37         <li>
  38                 <a href="../modules/luci.dispatcher.html">luci.dispatcher</a>
  39         </li>
  40
  41         <li>
  42                 <a href="../modules/luci.http.protocol.html">luci.http.protocol</a>
  43         </li>
  44
  45         <li>
  46                 <a href="../modules/luci.http.protocol.conditionals.html">luci.http.protocol.conditionals</a>
  47         </li>
  48
  49         <li>
  50                 <a href="../modules/luci.http.protocol.date.html">luci.http.protocol.date</a>
  51         </li>
  52
  53         <li>
  54                 <a href="../modules/luci.http.protocol.mime.html">luci.http.protocol.mime</a>
  55         </li>
  56
  57         <li>
  58                 <a href="../modules/luci.i18n.html">luci.i18n</a>
  59         </li>
  60
  61         <li>
  62                 <a href="../modules/luci.ip.html">luci.ip</a>
  63         </li>
  64
  65         <li>
  66                 <a href="../modules/luci.ip.cidr.html">luci.ip.cidr</a>
  67         </li>
  68
  69         <li>
  70                 <a href="../modules/luci.jsonc.html">luci.jsonc</a>
  71         </li>
  72
  73         <li>
  74                 <a href="../modules/luci.jsonc.parser.html">luci.jsonc.parser</a>
  75         </li>
  76
  77         <li>
  78                 <a href="../modules/luci.sys.init.html">luci.sys.init</a>
  79         </li>
  80
  81         <li>
  82                 <a href="../modules/luci.sys.iptparser.html">luci.sys.iptparser</a>
  83         </li>
  84
  85         <li>
  86                 <a href="../modules/luci.sys.net.html">luci.sys.net</a>
  87         </li>
  88
  89         <li>
  90                 <a href="../modules/luci.sys.process.html">luci.sys.process</a>
  91         </li>
  92
  93         <li>
  94                 <a href="../modules/luci.sys.user.html">luci.sys.user</a>
  95         </li>
  96
  97         <li>
  98                 <a href="../modules/luci.sys.wifi.html">luci.sys.wifi</a>
  99         </li>
 100
 101         <li>
 102                 <a href="../modules/nixio.html">nixio</a>
 103         </li>
 104
 105         <li>
 106                 <a href="../modules/nixio.CHANGELOG.html">nixio.CHANGELOG</a>
 107         </li>
 108
 109         <li>
 110                 <a href="../modules/nixio.CryptoHash.html">nixio.CryptoHash</a>
 111         </li>
 112
 113         <li><strong>nixio.File</strong></li>
 114
 115         <li>
 116                 <a href="../modules/nixio.README.html">nixio.README</a>
 117         </li>
 118
 119         <li>
 120                 <a href="../modules/nixio.Socket.html">nixio.Socket</a>
 121         </li>
 122
 123         <li>
 124                 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
 125         </li>
 126
 127         <li>
 128                 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
 129         </li>
 130
 131         <li>
 132                 <a href="../modules/nixio.UnifiedIO.html">nixio.UnifiedIO</a>
 133         </li>
 134
 135         <li>
 136                 <a href="../modules/nixio.bin.html">nixio.bin</a>
 137         </li>
 138
 139         <li>
 140                 <a href="../modules/nixio.bit.html">nixio.bit</a>
 141         </li>
 142
 143         <li>
 144                 <a href="../modules/nixio.crypto.html">nixio.crypto</a>
 145         </li>
 146
 147         <li>
 148                 <a href="../modules/nixio.fs.html">nixio.fs</a>
 149         </li>
 150
 151 </ul>
 152
 153
 154
 155 <!-- File list -->
 156
 157
 158
 159
 160
 161
 162
 163 </div><!-- id="navigation" -->
 164
 165 <div id="content">
 166
 167 <h1>Object Instance <code>nixio.File</code></h1>
 168
 169 <p>
 170  Large File Object.
 171  Large file operations are supported up to 52 bits if the Lua number type is
 172  double (default).</p>
 173
 174
 175
 176
 177
 178
 179
 180 <h2>Functions</h2>
 181 <table class="function_list">
 182
 183         <tr>
 184         <td class="name" nowrap><a href="#File.close">File:close</a>&nbsp;()</td>
 185         <td class="summary">
 186  Close the file descriptor.</td>
 187         </tr>
 188
 189         <tr>
 190         <td class="name" nowrap><a href="#File.fileno">File:fileno</a>&nbsp;()</td>
 191         <td class="summary">
 192  Get the number of the filedescriptor.</td>
 193         </tr>
 194
 195         <tr>
 196         <td class="name" nowrap><a href="#File.lock">File:lock</a>&nbsp;(command, length)</td>
 197         <td class="summary">
 198  Apply or test a lock on the file.</td>
 199         </tr>
 200
 201         <tr>
 202         <td class="name" nowrap><a href="#File.read">File:read</a>&nbsp;(length)</td>
 203         <td class="summary">
 204  Read from a file descriptor.</td>
 205         </tr>
 206
 207         <tr>
 208         <td class="name" nowrap><a href="#File.seek">File:seek</a>&nbsp;(offset, whence)</td>
 209         <td class="summary">
 210  Reposition read / write offset of the file descriptor.</td>
 211         </tr>
 212
 213         <tr>
 214         <td class="name" nowrap><a href="#File.setblocking">File:setblocking</a>&nbsp;(blocking)</td>
 215         <td class="summary">
 216  (POSIX) Set the blocking mode of the file descriptor.</td>
 217         </tr>
 218
 219         <tr>
 220         <td class="name" nowrap><a href="#File.stat">File:stat</a>&nbsp;(field)</td>
 221         <td class="summary">
 222  Get file status and attributes.</td>
 223         </tr>
 224
 225         <tr>
 226         <td class="name" nowrap><a href="#File.sync">File:sync</a>&nbsp;(data_only)</td>
 227         <td class="summary">
 228  Synchronizes the file with the storage device.</td>
 229         </tr>
 230
 231         <tr>
 232         <td class="name" nowrap><a href="#File.tell">File:tell</a>&nbsp;()</td>
 233         <td class="summary">
 234  Return the current read / write offset of the file descriptor.</td>
 235         </tr>
 236
 237         <tr>
 238         <td class="name" nowrap><a href="#File.write">File:write</a>&nbsp;(buffer, offset, length)</td>
 239         <td class="summary">
 240  Write to the file descriptor.</td>
 241         </tr>
 242
 243 </table>
 244
 245
 246
 247
 248
 249
 250 <br/>
 251 <br/>
 252
 253
 254 <h2><a name="functions"></a>Functions</h2>
 255 <dl class="function">
 256
 257
 258
 259 <dt><a name="File.close"></a><strong>File:close</strong>&nbsp;()</dt>
 260 <dd>
 261
 262  Close the file descriptor.
 263
 264
 265
 266
 267
 268
 269
 270 <h3>Return value:</h3>
 271 true
 272
 273
 274
 275 </dd>
 276
 277
 278
 279
 280 <dt><a name="File.fileno"></a><strong>File:fileno</strong>&nbsp;()</dt>
 281 <dd>
 282
 283  Get the number of the filedescriptor.
 284
 285
 286
 287
 288
 289
 290
 291 <h3>Return value:</h3>
 292 file descriptor number
 293
 294
 295
 296 </dd>
 297
 298
 299
 300
 301 <dt><a name="File.lock"></a><strong>File:lock</strong>&nbsp;(command, length)</dt>
 302 <dd>
 303
 304  Apply or test a lock on the file.
 305
 306
 307 <h3>Parameters</h3>
 308 <ul>
 309
 310         <li>
 311           command: Locking Command ["lock", "tlock", "ulock", "test"]
 312         </li>
 313
 314         <li>
 315           length: Amount of Bytes to lock from current offset (optional)
 316         </li>
 317
 318 </ul>
 319
 320
 321
 322
 323 <h3>Usage</h3>
 324 <ul>
 325
 326         <li>This function calls lockf() on POSIX and _locking() on Windows.
 327
 328         <li>The "lock" command is blocking, "tlock" is non-blocking,
 329  "ulock" unlocks and "test" only tests for the lock.
 330
 331         <li>The "test" command is not available on Windows.
 332
 333         <li>Locks are by default advisory on POSIX, but mandatory on Windows.
 334
 335 </ul>
 336
 337
 338
 339 <h3>Return value:</h3>
 340 true
 341
 342
 343
 344 </dd>
 345
 346
 347
 348
 349 <dt><a name="File.read"></a><strong>File:read</strong>&nbsp;(length)</dt>
 350 <dd>
 351
 352  Read from a file descriptor.
 353
 354
 355 <h3>Parameters</h3>
 356 <ul>
 357
 358         <li>
 359           length: Amount of data to read (in Bytes).
 360         </li>
 361
 362 </ul>
 363
 364
 365
 366
 367 <h3>Usage</h3>
 368 <ul>
 369
 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.
 374
 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.
 378
 379 </ul>
 380
 381
 382
 383 <h3>Return value:</h3>
 384 buffer containing data successfully read
 385
 386
 387
 388 </dd>
 389
 390
 391
 392
 393 <dt><a name="File.seek"></a><strong>File:seek</strong>&nbsp;(offset, whence)</dt>
 394 <dd>
 395
 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.
 399
 400
 401 <h3>Parameters</h3>
 402 <ul>
 403
 404         <li>
 405           offset: File Offset
 406         </li>
 407
 408         <li>
 409           whence: Starting point [<strong>"set"</strong>, "cur", "end"]
 410         </li>
 411
 412 </ul>
 413
 414
 415
 416
 417 <h3>Usage:</h3>
 418 This function calls lseek().
 419
 420
 421
 422 <h3>Return value:</h3>
 423 new (absolute) offset position
 424
 425
 426
 427 </dd>
 428
 429
 430
 431
 432 <dt><a name="File.setblocking"></a><strong>File:setblocking</strong>&nbsp;(blocking)</dt>
 433 <dd>
 434
 435  (POSIX) Set the blocking mode of the file descriptor.
 436
 437
 438 <h3>Parameters</h3>
 439 <ul>
 440
 441         <li>
 442           blocking: (boolean)
 443         </li>
 444
 445 </ul>
 446
 447
 448
 449
 450
 451
 452 <h3>Return value:</h3>
 453 true
 454
 455
 456
 457 </dd>
 458
 459
 460
 461
 462 <dt><a name="File.stat"></a><strong>File:stat</strong>&nbsp;(field)</dt>
 463 <dd>
 464
 465  Get file status and attributes.
 466
 467
 468 <h3>Parameters</h3>
 469 <ul>
 470
 471         <li>
 472           field: Only return a specific field, not the whole table (optional)
 473         </li>
 474
 475 </ul>
 476
 477
 478
 479
 480 <h3>Usage:</h3>
 481 This function calls fstat().
 482
 483
 484
 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>
 493  <li>ino = Inode</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>
 502  </ul>
 503
 504
 505
 506 </dd>
 507
 508
 509
 510
 511 <dt><a name="File.sync"></a><strong>File:sync</strong>&nbsp;(data_only)</dt>
 512 <dd>
 513
 514  Synchronizes the file with the storage device.
 515  Returns when the file is successfully written to the disk.
 516
 517
 518 <h3>Parameters</h3>
 519 <ul>
 520
 521         <li>
 522           data_only: Do not synchronize the metadata. (optional, boolean)
 523         </li>
 524
 525 </ul>
 526
 527
 528
 529
 530 <h3>Usage</h3>
 531 <ul>
 532
 533         <li>This function calls fsync() when data_only equals false
 534  otherwise fdatasync(), on Windows _commit() is used instead.
 535
 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.
 538
 539 </ul>
 540
 541
 542
 543 <h3>Return value:</h3>
 544 true
 545
 546
 547
 548 </dd>
 549
 550
 551
 552
 553 <dt><a name="File.tell"></a><strong>File:tell</strong>&nbsp;()</dt>
 554 <dd>
 555
 556  Return the current read / write offset of the file descriptor.
 557
 558
 559
 560
 561
 562 <h3>Usage:</h3>
 563 This function calls lseek() with offset 0 from the current position.
 564
 565
 566
 567 <h3>Return value:</h3>
 568 offset position
 569
 570
 571
 572 </dd>
 573
 574
 575
 576
 577 <dt><a name="File.write"></a><strong>File:write</strong>&nbsp;(buffer, offset, length)</dt>
 578 <dd>
 579
 580  Write to the file descriptor.
 581
 582
 583 <h3>Parameters</h3>
 584 <ul>
 585
 586         <li>
 587           buffer: Buffer holding the data to be written.
 588         </li>
 589
 590         <li>
 591           offset: Offset to start reading the buffer from. (optional)
 592         </li>
 593
 594         <li>
 595           length: Length of chunk to read from the buffer. (optional)
 596         </li>
 597
 598 </ul>
 599
 600
 601
 602
 603 <h3>Usage</h3>
 604 <ul>
 605
 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.
 610
 611         <li>Unlike standard Lua indexing the lowest offset and default is 0.
 612
 613 </ul>
 614
 615
 616
 617 <h3>Return value:</h3>
 618 number of bytes written
 619
 620
 621
 622 </dd>
 623
 624
 625 </dl>
 626
 627
 628
 629
 630
 631 </div> <!-- id="content" -->
 632
 633 </div> <!-- id="main" -->
 634
 635 <div id="about">
 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" -->
 638
 639 </div> <!-- id="container" -->
 640 </body>
 641 </html>