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