Module 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
| is_socket () | Test whether the I/O-Descriptor is a socket. |
| is_tls_socket () | Test whether the I/O-Descriptor is a TLS socket. |
| is_file () | Test whether the I/O-Descriptor is a file. |
| readall (length) | Read a block of data and wait until all data is available. |
| writeall (block) | Write a block of data and wait until all data is written. |
| linesource (limit) | Create a line-based iterator. |
| blocksource (blocksize, limit) | Create a block-based iterator. |
| sink (close_when_done) | Create a sink. |
| copy (fdout, size) | Copy data from the current descriptor to another one. |
| copyz (fdout, size) | Copy data from the current descriptor to another one using kernel-space copying if possible. |
| close () | Close the descriptor. |
Functions
- is_socket ()
-
Test whether the I/O-Descriptor is a socket.
Returns:
-
boolean
- is_tls_socket ()
-
Test whether the I/O-Descriptor is a TLS socket.
Returns:
-
boolean
- is_file ()
-
Test whether the I/O-Descriptor is a file.
Returns:
-
boolean
- readall (length)
-
Read a block of data and wait until all data is available.
Parameters:
- length Bytes to read (optional)
Returns:
- 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
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.
- writeall (block)
-
Write a block of data and wait until all data is written.
Parameters:
- block Bytes to write
Returns:
- 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
Usage:
This function uses the low-level write function of the descriptor.
If the descriptor is non-blocking this function may fail with EAGAIN.
- 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
Returns:
-
Line-based Iterator
Usage:
This function uses the low-level read function of the descriptor.
<strong>Note:</strong> 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.
- blocksource (blocksize, limit)
-
Create a block-based iterator.
Parameters:
- blocksize Advisory blocksize (optional)
- limit Amount of data to consume (optional)
Returns:
-
Block-based Iterator
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.
- 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)
Returns:
-
Sink
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.
- copy (fdout, size)
-
Copy data from the current descriptor to another one.
Parameters:
- fdout Target Descriptor
- size Bytes to copy (optional)
Returns:
- 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
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.
- 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)
Returns:
- 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
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.
- close ()
-
Close the descriptor.
Returns:
-
true
Usage:
If the descriptor is a TLS-socket the underlying descriptor is closed without touching the TLS connection.