# 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