documentation/api/modules/nixio.UnifiedIO.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>
 114                 <a href="../modules/nixio.File.html">nixio.File</a>
 115         </li>
 116
 117         <li>
 118                 <a href="../modules/nixio.README.html">nixio.README</a>
 119         </li>
 120
 121         <li>
 122                 <a href="../modules/nixio.Socket.html">nixio.Socket</a>
 123         </li>
 124
 125         <li>
 126                 <a href="../modules/nixio.TLSContext.html">nixio.TLSContext</a>
 127         </li>
 128
 129         <li>
 130                 <a href="../modules/nixio.TLSSocket.html">nixio.TLSSocket</a>
 131         </li>
 132
 133         <li><strong>nixio.UnifiedIO</strong></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.UnifiedIO</code></h1>
 168
 169 <p>
 170  Unified high-level I/O utility API for Files, Sockets and TLS-Sockets.
 171  These functions are added to the object function tables by doing <strong>
 172  require "nixio.util"</strong>, can be used on all nixio IO  Descriptors and
 173  are based on the shared low-level read() and write() functions.</p>
 174
 175
 176
 177
 178
 179
 180
 181 <h2>Functions</h2>
 182 <table class="function_list">
 183
 184         <tr>
 185         <td class="name" nowrap><a href="#UnifiedIO.blocksource">UnifiedIO:blocksource</a>&nbsp;(blocksize, limit)</td>
 186         <td class="summary">
 187  Create a block-based iterator.</td>
 188         </tr>
 189
 190         <tr>
 191         <td class="name" nowrap><a href="#UnifiedIO.close">UnifiedIO:close</a>&nbsp;()</td>
 192         <td class="summary">
 193  Close the descriptor.</td>
 194         </tr>
 195
 196         <tr>
 197         <td class="name" nowrap><a href="#UnifiedIO.copy">UnifiedIO:copy</a>&nbsp;(fdout, size)</td>
 198         <td class="summary">
 199  Copy data from the current descriptor to another one.</td>
 200         </tr>
 201
 202         <tr>
 203         <td class="name" nowrap><a href="#UnifiedIO.copyz">UnifiedIO:copyz</a>&nbsp;(fdout, size)</td>
 204         <td class="summary">
 205  Copy data from the current descriptor to another one using kernel-space
 206  copying if possible.</td>
 207         </tr>
 208
 209         <tr>
 210         <td class="name" nowrap><a href="#UnifiedIO.is_file">UnifiedIO:is_file</a>&nbsp;()</td>
 211         <td class="summary">
 212  Test whether the I/O-Descriptor is a file.</td>
 213         </tr>
 214
 215         <tr>
 216         <td class="name" nowrap><a href="#UnifiedIO.is_socket">UnifiedIO:is_socket</a>&nbsp;()</td>
 217         <td class="summary">
 218  Test whether the I/O-Descriptor is a socket.</td>
 219         </tr>
 220
 221         <tr>
 222         <td class="name" nowrap><a href="#UnifiedIO.is_tls_socket">UnifiedIO:is_tls_socket</a>&nbsp;()</td>
 223         <td class="summary">
 224  Test whether the I/O-Descriptor is a TLS socket.</td>
 225         </tr>
 226
 227         <tr>
 228         <td class="name" nowrap><a href="#UnifiedIO.linesource">UnifiedIO:linesource</a>&nbsp;(limit)</td>
 229         <td class="summary">
 230  Create a line-based iterator.</td>
 231         </tr>
 232
 233         <tr>
 234         <td class="name" nowrap><a href="#UnifiedIO.readall">UnifiedIO:readall</a>&nbsp;(length)</td>
 235         <td class="summary">
 236  Read a block of data and wait until all data is available.</td>
 237         </tr>
 238
 239         <tr>
 240         <td class="name" nowrap><a href="#UnifiedIO.sink">UnifiedIO:sink</a>&nbsp;(close_when_done)</td>
 241         <td class="summary">
 242  Create a sink.</td>
 243         </tr>
 244
 245         <tr>
 246         <td class="name" nowrap><a href="#UnifiedIO.writeall">UnifiedIO:writeall</a>&nbsp;(block)</td>
 247         <td class="summary">
 248  Write a block of data and wait until all data is written.</td>
 249         </tr>
 250
 251 </table>
 252
 253
 254
 255
 256
 257
 258 <br/>
 259 <br/>
 260
 261
 262 <h2><a name="functions"></a>Functions</h2>
 263 <dl class="function">
 264
 265
 266
 267 <dt><a name="UnifiedIO.blocksource"></a><strong>UnifiedIO:blocksource</strong>&nbsp;(blocksize, limit)</dt>
 268 <dd>
 269
 270  Create a block-based iterator.
 271
 272
 273 <h3>Parameters</h3>
 274 <ul>
 275
 276         <li>
 277           blocksize: Advisory blocksize (optional)
 278         </li>
 279
 280         <li>
 281           limit: Amount of data to consume (optional)
 282         </li>
 283
 284 </ul>
 285
 286
 287
 288
 289 <h3>Usage</h3>
 290 <ul>
 291
 292         <li>This function uses the low-level read function of the descriptor.
 293
 294         <li>The blocksize given is only advisory and to be seen as an upper limit,
 295  if an underlying read returns less bytes the chunk is nevertheless returned.
 296
 297         <li>If the limit parameter is ommited, the iterator returns data
 298  until an end-of-file, end-of-stream, connection shutdown or similar happens.
 299
 300         <li>The iterator will not buffer so it is safe to mix with calls to read.
 301
 302         <li>If the descriptor is non-blocking the iterator may fail with EAGAIN.
 303
 304         <li>The iterator can be used as an LTN12 source.
 305
 306 </ul>
 307
 308
 309
 310 <h3>Return value:</h3>
 311 Block-based Iterator
 312
 313
 314
 315 </dd>
 316
 317
 318
 319
 320 <dt><a name="UnifiedIO.close"></a><strong>UnifiedIO:close</strong>&nbsp;()</dt>
 321 <dd>
 322
 323  Close the descriptor.
 324
 325
 326
 327
 328
 329 <h3>Usage:</h3>
 330 If the descriptor is a TLS-socket the underlying descriptor is
 331  closed without touching the TLS connection.
 332
 333
 334
 335 <h3>Return value:</h3>
 336 true
 337
 338
 339
 340 </dd>
 341
 342
 343
 344
 345 <dt><a name="UnifiedIO.copy"></a><strong>UnifiedIO:copy</strong>&nbsp;(fdout, size)</dt>
 346 <dd>
 347
 348  Copy data from the current descriptor to another one.
 349
 350
 351 <h3>Parameters</h3>
 352 <ul>
 353
 354         <li>
 355           fdout: Target Descriptor
 356         </li>
 357
 358         <li>
 359           size: Bytes to copy (optional)
 360         </li>
 361
 362 </ul>
 363
 364
 365
 366
 367 <h3>Usage</h3>
 368 <ul>
 369
 370         <li>This function uses the blocksource function of the source descriptor
 371  and the sink function of the target descriptor.
 372
 373         <li>If the limit parameter is ommited, data is copied
 374  until an end-of-file, end-of-stream, connection shutdown or similar happens.
 375
 376         <li>If the descriptor is non-blocking the function may fail with EAGAIN.
 377
 378 </ul>
 379
 380
 381
 382 <h3>Return values:</h3>
 383 <ol>
 384
 385         <li>bytes that were successfully written if no error occured
 386
 387         <li>- reserved for error code -
 388
 389         <li>- reserved for error message -
 390
 391         <li>bytes that were successfully written even if an error occured
 392
 393 </ol>
 394
 395
 396
 397 </dd>
 398
 399
 400
 401
 402 <dt><a name="UnifiedIO.copyz"></a><strong>UnifiedIO:copyz</strong>&nbsp;(fdout, size)</dt>
 403 <dd>
 404
 405  Copy data from the current descriptor to another one using kernel-space
 406  copying if possible.
 407
 408
 409 <h3>Parameters</h3>
 410 <ul>
 411
 412         <li>
 413           fdout: Target Descriptor
 414         </li>
 415
 416         <li>
 417           size: Bytes to copy (optional)
 418         </li>
 419
 420 </ul>
 421
 422
 423
 424
 425 <h3>Usage</h3>
 426 <ul>
 427
 428         <li>This function uses the sendfile() syscall to copy the data or the
 429  blocksource function of the source descriptor and the sink function
 430  of the target descriptor as a fallback mechanism.
 431
 432         <li>If the limit parameter is ommited, data is copied
 433  until an end-of-file, end-of-stream, connection shutdown or similar happens.
 434
 435         <li>If the descriptor is non-blocking the function may fail with EAGAIN.
 436
 437 </ul>
 438
 439
 440
 441 <h3>Return values:</h3>
 442 <ol>
 443
 444         <li>bytes that were successfully written if no error occured
 445
 446         <li>- reserved for error code -
 447
 448         <li>- reserved for error message -
 449
 450         <li>bytes that were successfully written even if an error occured
 451
 452 </ol>
 453
 454
 455
 456 </dd>
 457
 458
 459
 460
 461 <dt><a name="UnifiedIO.is_file"></a><strong>UnifiedIO:is_file</strong>&nbsp;()</dt>
 462 <dd>
 463
 464  Test whether the I/O-Descriptor is a file.
 465
 466
 467
 468
 469
 470
 471
 472 <h3>Return value:</h3>
 473 boolean
 474
 475
 476
 477 </dd>
 478
 479
 480
 481
 482 <dt><a name="UnifiedIO.is_socket"></a><strong>UnifiedIO:is_socket</strong>&nbsp;()</dt>
 483 <dd>
 484
 485  Test whether the I/O-Descriptor is a socket.
 486
 487
 488
 489
 490
 491
 492
 493 <h3>Return value:</h3>
 494 boolean
 495
 496
 497
 498 </dd>
 499
 500
 501
 502
 503 <dt><a name="UnifiedIO.is_tls_socket"></a><strong>UnifiedIO:is_tls_socket</strong>&nbsp;()</dt>
 504 <dd>
 505
 506  Test whether the I/O-Descriptor is a TLS socket.
 507
 508
 509
 510
 511
 512
 513
 514 <h3>Return value:</h3>
 515 boolean
 516
 517
 518
 519 </dd>
 520
 521
 522
 523
 524 <dt><a name="UnifiedIO.linesource"></a><strong>UnifiedIO:linesource</strong>&nbsp;(limit)</dt>
 525 <dd>
 526
 527  Create a line-based iterator.
 528  Lines may end with either \n or \r\n, these control chars are not included
 529  in the return value.
 530
 531
 532 <h3>Parameters</h3>
 533 <ul>
 534
 535         <li>
 536           limit: Line limit
 537         </li>
 538
 539 </ul>
 540
 541
 542
 543
 544 <h3>Usage</h3>
 545 <ul>
 546
 547         <li>This function uses the low-level read function of the descriptor.
 548
 549         <li><strong>Note:</strong> This function uses an internal buffer to read
 550  ahead. Do NOT mix calls to read(all) and the returned iterator. If you want
 551  to stop reading line-based and want to use the read(all) functions instead
 552  you can pass "true" to the iterator which will flush the buffer
 553  and return the bufferd data.
 554
 555         <li>If the limit parameter is ommited, this function uses the nixio
 556  buffersize (8192B by default).
 557
 558         <li>If the descriptor is non-blocking the iterator may fail with EAGAIN.
 559
 560         <li>The iterator can be used as an LTN12 source.
 561
 562 </ul>
 563
 564
 565
 566 <h3>Return value:</h3>
 567 Line-based Iterator
 568
 569
 570
 571 </dd>
 572
 573
 574
 575
 576 <dt><a name="UnifiedIO.readall"></a><strong>UnifiedIO:readall</strong>&nbsp;(length)</dt>
 577 <dd>
 578
 579  Read a block of data and wait until all data is available.
 580
 581
 582 <h3>Parameters</h3>
 583 <ul>
 584
 585         <li>
 586           length: Bytes to read (optional)
 587         </li>
 588
 589 </ul>
 590
 591
 592
 593
 594 <h3>Usage</h3>
 595 <ul>
 596
 597         <li>This function uses the low-level read function of the descriptor.
 598
 599         <li>If the length parameter is ommited, this function returns all data
 600  that can be read before an end-of-file, end-of-stream, connection shutdown
 601  or similar happens.
 602
 603         <li>If the descriptor is non-blocking this function may fail with EAGAIN.
 604
 605 </ul>
 606
 607
 608
 609 <h3>Return values:</h3>
 610 <ol>
 611
 612         <li>data that was successfully read if no error occured
 613
 614         <li>- reserved for error code -
 615
 616         <li>- reserved for error message -
 617
 618         <li>data that was successfully read even if an error occured
 619
 620 </ol>
 621
 622
 623
 624 </dd>
 625
 626
 627
 628
 629 <dt><a name="UnifiedIO.sink"></a><strong>UnifiedIO:sink</strong>&nbsp;(close_when_done)</dt>
 630 <dd>
 631
 632  Create a sink.
 633  This sink will simply write all data that it receives and optionally
 634  close the descriptor afterwards.
 635
 636
 637 <h3>Parameters</h3>
 638 <ul>
 639
 640         <li>
 641           close_when_done: (optional, boolean)
 642         </li>
 643
 644 </ul>
 645
 646
 647
 648
 649 <h3>Usage</h3>
 650 <ul>
 651
 652         <li>This function uses the writeall function of the descriptor.
 653
 654         <li>If the descriptor is non-blocking the sink may fail with EAGAIN.
 655
 656         <li>The iterator can be used as an LTN12 sink.
 657
 658 </ul>
 659
 660
 661
 662 <h3>Return value:</h3>
 663 Sink
 664
 665
 666
 667 </dd>
 668
 669
 670
 671
 672 <dt><a name="UnifiedIO.writeall"></a><strong>UnifiedIO:writeall</strong>&nbsp;(block)</dt>
 673 <dd>
 674
 675  Write a block of data and wait until all data is written.
 676
 677
 678 <h3>Parameters</h3>
 679 <ul>
 680
 681         <li>
 682           block: Bytes to write
 683         </li>
 684
 685 </ul>
 686
 687
 688
 689
 690 <h3>Usage</h3>
 691 <ul>
 692
 693         <li>This function uses the low-level write function of the descriptor.
 694
 695         <li>If the descriptor is non-blocking this function may fail with EAGAIN.
 696
 697 </ul>
 698
 699
 700
 701 <h3>Return values:</h3>
 702 <ol>
 703
 704         <li>bytes that were successfully written if no error occured
 705
 706         <li>- reserved for error code -
 707
 708         <li>- reserved for error message -
 709
 710         <li>bytes that were successfully written even if an error occured
 711
 712 </ol>
 713
 714
 715
 716 </dd>
 717
 718
 719 </dl>
 720
 721
 722
 723
 724
 725 </div> <!-- id="content" -->
 726
 727 </div> <!-- id="main" -->
 728
 729 <div id="about">
 730         <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>
 731 </div> <!-- id="about" -->
 732
 733 </div> <!-- id="container" -->
 734 </body>
 735 </html>