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:

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

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

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

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

Valid XHTML 1.0!