documentation: Fix typos (found by codespell)
[project/luci.git] / 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>