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