Rework LuCI build system
[project/luci.git] / libs / luci-lib-nixio / docsrc / nixio.UnifiedIO.lua
1 --- Unified high-level I/O utility API for Files, Sockets and TLS-Sockets.
2 -- These functions are added to the object function tables by doing <strong>
3 -- require "nixio.util"</strong>, can be used on all nixio IO  Descriptors and
4 -- are based on the shared low-level read() and write() functions.
5 -- @cstyle      instance
6 module "nixio.UnifiedIO"
7
8 --- Test whether the I/O-Descriptor is a socket. 
9 -- @class function
10 -- @name UnifiedIO.is_socket
11 -- @return      boolean
12
13 --- Test whether the I/O-Descriptor is a TLS socket. 
14 -- @class function
15 -- @name UnifiedIO.is_tls_socket
16 -- @return      boolean
17
18 --- Test whether the I/O-Descriptor is a file. 
19 -- @class function
20 -- @name UnifiedIO.is_file
21 -- @return      boolean
22
23 --- Read a block of data and wait until all data is available.
24 -- @class function
25 -- @name UnifiedIO.readall
26 -- @usage This function uses the low-level read function of the descriptor.
27 -- @usage If the length parameter is ommited, this function returns all data
28 -- that can be read before an end-of-file, end-of-stream, connection shutdown
29 -- or similar happens.
30 -- @usage If the descriptor is non-blocking this function may fail with EAGAIN.
31 -- @param       length  Bytes to read (optional)
32 -- @return      data that was successfully read if no error occured
33 -- @return      - reserved for error code -
34 -- @return      - reserved for error message -
35 -- @return  data that was successfully read even if an error occured
36
37 --- Write a block of data and wait until all data is written.
38 -- @class function
39 -- @name UnifiedIO.writeall
40 -- @usage This function uses the low-level write function of the descriptor.
41 -- @usage If the descriptor is non-blocking this function may fail with EAGAIN.
42 -- @param       block   Bytes to write
43 -- @return      bytes that were successfully written if no error occured
44 -- @return      - reserved for error code -
45 -- @return      - reserved for error message -
46 -- @return  bytes that were successfully written even if an error occured
47
48 --- Create a line-based iterator.
49 -- Lines may end with either \n or \r\n, these control chars are not included
50 -- in the return value.
51 -- @class function
52 -- @name UnifiedIO.linesource
53 -- @usage This function uses the low-level read function of the descriptor.
54 -- @usage <strong>Note:</strong> This function uses an internal buffer to read
55 -- ahead. Do NOT mix calls to read(all) and the returned iterator. If you want
56 -- to stop reading line-based and want to use the read(all) functions instead
57 -- you can pass "true" to the iterator which will flush the buffer 
58 -- and return the bufferd data.
59 -- @usage If the limit parameter is ommited, this function uses the nixio
60 -- buffersize (8192B by default).
61 -- @usage If the descriptor is non-blocking the iterator may fail with EAGAIN.
62 -- @usage The iterator can be used as an LTN12 source.
63 -- @param       limit   Line limit
64 -- @return      Line-based Iterator
65
66 --- Create a block-based iterator.
67 -- @class function
68 -- @name UnifiedIO.blocksource
69 -- @usage This function uses the low-level read function of the descriptor.
70 -- @usage The blocksize given is only advisory and to be seen as an upper limit,
71 -- if an underlying read returns less bytes the chunk is nevertheless returned.
72 -- @usage If the limit parameter is ommited, the iterator returns data
73 -- until an end-of-file, end-of-stream, connection shutdown or similar happens.
74 -- @usage The iterator will not buffer so it is safe to mix with calls to read.
75 -- @usage If the descriptor is non-blocking the iterator may fail with EAGAIN.
76 -- @usage The iterator can be used as an LTN12 source.
77 -- @param       blocksize       Advisory blocksize (optional)
78 -- @param       limit           Amount of data to consume (optional)
79 -- @return      Block-based Iterator
80
81 --- Create a sink.
82 -- This sink will simply write all data that it receives and optionally
83 -- close the descriptor afterwards.
84 -- @class function
85 -- @name UnifiedIO.sink
86 -- @usage This function uses the writeall function of the descriptor.
87 -- @usage If the descriptor is non-blocking the sink may fail with EAGAIN.
88 -- @usage The iterator can be used as an LTN12 sink.
89 -- @param       close_when_done (optional, boolean)
90 -- @return      Sink
91
92 --- Copy data from the current descriptor to another one.
93 -- @class function
94 -- @name UnifiedIO.copy
95 -- @usage This function uses the blocksource function of the source descriptor
96 -- and the sink function of the target descriptor.
97 -- @usage If the limit parameter is ommited, data is copied
98 -- until an end-of-file, end-of-stream, connection shutdown or similar happens.
99 -- @usage If the descriptor is non-blocking the function may fail with EAGAIN.
100 -- @param       fdout Target Descriptor
101 -- @param       size  Bytes to copy (optional)
102 -- @return      bytes that were successfully written if no error occured
103 -- @return      - reserved for error code -
104 -- @return      - reserved for error message -
105 -- @return  bytes that were successfully written even if an error occured
106
107 --- Copy data from the current descriptor to another one using kernel-space
108 -- copying if possible.
109 -- @class function
110 -- @name UnifiedIO.copyz
111 -- @usage This function uses the sendfile() syscall to copy the data or the
112 -- blocksource function of the source descriptor and the sink function
113 -- of the target descriptor as a fallback mechanism.
114 -- @usage If the limit parameter is ommited, data is copied
115 -- until an end-of-file, end-of-stream, connection shutdown or similar happens.
116 -- @usage If the descriptor is non-blocking the function may fail with EAGAIN.
117 -- @param       fdout Target Descriptor
118 -- @param       size  Bytes to copy (optional)
119 -- @return      bytes that were successfully written if no error occured
120 -- @return      - reserved for error code -
121 -- @return      - reserved for error message -
122 -- @return  bytes that were successfully written even if an error occured
123
124 --- Close the descriptor.
125 -- @class function
126 -- @name UnifiedIO.close
127 -- @usage       If the descriptor is a TLS-socket the underlying descriptor is
128 -- closed without touching the TLS connection.
129 -- @return      true