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

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:

  1. bytes that were successfully written if no error occured
  2. - reserved for error code -
  3. - reserved for error message -
  4. 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:

  1. bytes that were successfully written if no error occured
  2. - reserved for error code -
  3. - reserved for error message -
  4. 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:

  1. data that was successfully read if no error occured
  2. - reserved for error code -
  3. - reserved for error message -
  4. 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:

  1. bytes that were successfully written if no error occured
  2. - reserved for error code -
  3. - reserved for error message -
  4. bytes that were successfully written even if an error occured

Valid XHTML 1.0!