Object Instance nixio.UnifiedIO
+
++ Unified high-level I/O utility API for Files, Sockets and TLS-Sockets. + These functions are added to the object function tables by doing + require "nixio.util", can be used on all nixio IO Descriptors and + are based on the shared low-level read() and write() functions.
+ + + + + + + +Functions
+| UnifiedIO:blocksource (blocksize, limit) | ++ Create a block-based iterator. | +
| UnifiedIO:close () | ++ Close the descriptor. | +
| UnifiedIO:copy (fdout, size) | ++ Copy data from the current descriptor to another one. | +
| UnifiedIO:copyz (fdout, size) | ++ Copy data from the current descriptor to another one using kernel-space + copying if possible. | +
| UnifiedIO:is_file () | ++ Test whether the I/O-Descriptor is a file. | +
| UnifiedIO:is_socket () | ++ Test whether the I/O-Descriptor is a socket. | +
| UnifiedIO:is_tls_socket () | ++ Test whether the I/O-Descriptor is a TLS socket. | +
| UnifiedIO:linesource (limit) | ++ Create a line-based iterator. | +
| UnifiedIO:readall (length) | ++ Read a block of data and wait until all data is available. | +
| UnifiedIO:sink (close_when_done) | ++ Create a sink. | +
| UnifiedIO:writeall (block) | ++ Write a block of data and wait until all data is written. | +
+
+ + +
Functions
+-
+
+
+
+
- UnifiedIO:blocksource (blocksize, limit) +
-
+
+ Create a block-based iterator.
+
+
+
Parameters
+-
+
+
- + blocksize: Advisory blocksize (optional) + + +
- + limit: Amount of data to consume (optional) + + +
Usage
+-
+
+
- This function uses the low-level read function of the descriptor. + +
- The blocksize given is only advisory and to be seen as an upper limit, + if an underlying read returns less bytes the chunk is nevertheless returned. + +
- If the limit parameter is ommited, the iterator returns data + until an end-of-file, end-of-stream, connection shutdown or similar happens. + +
- The iterator will not buffer so it is safe to mix with calls to read. + +
- If the descriptor is non-blocking the iterator may fail with EAGAIN. + +
- The iterator can be used as an LTN12 source. + +
Return value:
+Block-based Iterator + + + +
+
+
+
+
+ - UnifiedIO:close () +
-
+
+ Close the descriptor.
+
+
+
+
+
+
Usage:
+If the descriptor is a TLS-socket the underlying descriptor is + closed without touching the TLS connection. + + + +Return value:
+true + + + +
+
+
+
+
+ - UnifiedIO:copy (fdout, size) +
-
+
+ Copy data from the current descriptor to another one.
+
+
+
Parameters
+-
+
+
- + fdout: Target Descriptor + + +
- + size: Bytes to copy (optional) + + +
Usage
+-
+
+
- This function uses the blocksource function of the source descriptor + and the sink function of the target descriptor. + +
- If the limit parameter is ommited, data is copied + until an end-of-file, end-of-stream, connection shutdown or similar happens. + +
- If the descriptor is non-blocking the function may fail with EAGAIN. + +
Return values:
+-
+
+
- bytes that were successfully written if no error occured + +
- - reserved for error code - + +
- - reserved for error message - + +
- bytes that were successfully written even if an error occured + +
+
+
+
+
+ - UnifiedIO:copyz (fdout, size) +
-
+
+ Copy data from the current descriptor to another one using kernel-space
+ copying if possible.
+
+
+
Parameters
+-
+
+
- + fdout: Target Descriptor + + +
- + size: Bytes to copy (optional) + + +
Usage
+-
+
+
- This function uses the sendfile() syscall to copy the data or the + blocksource function of the source descriptor and the sink function + of the target descriptor as a fallback mechanism. + +
- If the limit parameter is ommited, data is copied + until an end-of-file, end-of-stream, connection shutdown or similar happens. + +
- If the descriptor is non-blocking the function may fail with EAGAIN. + +
Return values:
+-
+
+
- bytes that were successfully written if no error occured + +
- - reserved for error code - + +
- - reserved for error message - + +
- bytes that were successfully written even if an error occured + +
+
+
+
+
+ - UnifiedIO:is_file () +
-
+
+ Test whether the I/O-Descriptor is a file.
+
+
+
+
+
+
+
+
Return value:
+boolean + + + +
+
+
+
+
+ - UnifiedIO:is_socket () +
-
+
+ Test whether the I/O-Descriptor is a socket.
+
+
+
+
+
+
+
+
Return value:
+boolean + + + +
+
+
+
+
+ - UnifiedIO:is_tls_socket () +
-
+
+ Test whether the I/O-Descriptor is a TLS socket.
+
+
+
+
+
+
+
+
Return value:
+boolean + + + +
+
+
+
+
+ - UnifiedIO:linesource (limit) +
-
+
+ Create a line-based iterator.
+ Lines may end with either \n or \r\n, these control chars are not included
+ in the return value.
+
+
+
Parameters
+-
+
+
- + limit: Line limit + + +
Usage
+-
+
+
- This function uses the low-level read function of the descriptor. + +
- Note: This function uses an internal buffer to read + ahead. Do NOT mix calls to read(all) and the returned iterator. If you want + to stop reading line-based and want to use the read(all) functions instead + you can pass "true" to the iterator which will flush the buffer + and return the bufferd data. + +
- If the limit parameter is ommited, this function uses the nixio + buffersize (8192B by default). + +
- If the descriptor is non-blocking the iterator may fail with EAGAIN. + +
- The iterator can be used as an LTN12 source. + +
Return value:
+Line-based Iterator + + + +
+
+
+
+
+ - UnifiedIO:readall (length) +
-
+
+ Read a block of data and wait until all data is available.
+
+
+
Parameters
+-
+
+
- + length: Bytes to read (optional) + + +
Usage
+-
+
+
- This function uses the low-level read function of the descriptor. + +
- If the length parameter is ommited, this function returns all data + that can be read before an end-of-file, end-of-stream, connection shutdown + or similar happens. + +
- If the descriptor is non-blocking this function may fail with EAGAIN. + +
Return values:
+-
+
+
- data that was successfully read if no error occured + +
- - reserved for error code - + +
- - reserved for error message - + +
- data that was successfully read even if an error occured + +
+
+
+
+
+ - UnifiedIO:sink (close_when_done) +
-
+
+ Create a sink.
+ This sink will simply write all data that it receives and optionally
+ close the descriptor afterwards.
+
+
+
Parameters
+-
+
+
- + close_when_done: (optional, boolean) + + +
Usage
+-
+
+
- This function uses the writeall function of the descriptor. + +
- If the descriptor is non-blocking the sink may fail with EAGAIN. + +
- The iterator can be used as an LTN12 sink. + +
Return value:
+Sink + + + +
+
+
+
+
+ - UnifiedIO:writeall (block) +
-
+
+ Write a block of data and wait until all data is written.
+
+
+
Parameters
+-
+
+
- + block: Bytes to write + + +
Usage
+-
+
+
- This function uses the low-level write function of the descriptor. + +
- If the descriptor is non-blocking this function may fail with EAGAIN. + +
Return values:
+-
+
+
- bytes that were successfully written if no error occured + +
- - reserved for error code - + +
- - reserved for error message - + +
- bytes that were successfully written even if an error occured + +
+
+
+