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 omitted, 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 omitted, 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 occurred
- - reserved for error code -
- - reserved for error message -
- bytes that were successfully written even if an error occurred
- 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 omitted, 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 occurred
- - reserved for error code -
- - reserved for error message -
- bytes that were successfully written even if an error occurred
- 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 omitted, 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 omitted, 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 occurred
- - reserved for error code -
- - reserved for error message -
- data that was successfully read even if an error occurred
- 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 occurred
- - reserved for error code -
- - reserved for error message -
- bytes that were successfully written even if an error occurred