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