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