+++ /dev/null
---- Unified high-level I/O utility API for Files, Sockets and TLS-Sockets.
--- These functions are added to the object function tables by doing <strong>
--- require "nixio.util"</strong>, can be used on all nixio IO Descriptors and
--- are based on the shared low-level read() and write() functions.
--- @cstyle instance
-module "nixio.UnifiedIO"
-
---- Test whether the I/O-Descriptor is a socket.
--- @class function
--- @name UnifiedIO.is_socket
--- @return boolean
-
---- Test whether the I/O-Descriptor is a TLS socket.
--- @class function
--- @name UnifiedIO.is_tls_socket
--- @return boolean
-
---- Test whether the I/O-Descriptor is a file.
--- @class function
--- @name UnifiedIO.is_file
--- @return boolean
-
---- Read a block of data and wait until all data is available.
--- @class function
--- @name UnifiedIO.readall
--- @usage This function uses the low-level read function of the descriptor.
--- @usage 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.
--- @usage If the descriptor is non-blocking this function may fail with EAGAIN.
--- @param length Bytes to read (optional)
--- @return data that was successfully read if no error occured
--- @return - reserved for error code -
--- @return - reserved for error message -
--- @return data that was successfully read even if an error occured
-
---- Write a block of data and wait until all data is written.
--- @class function
--- @name UnifiedIO.writeall
--- @usage This function uses the low-level write function of the descriptor.
--- @usage If the descriptor is non-blocking this function may fail with EAGAIN.
--- @param block Bytes to write
--- @return bytes that were successfully written if no error occured
--- @return - reserved for error code -
--- @return - reserved for error message -
--- @return bytes that were successfully written even if an error occured
-
---- Create a line-based iterator.
--- Lines may end with either \n or \r\n, these control chars are not included
--- in the return value.
--- @class function
--- @name UnifiedIO.linesource
--- @usage This function uses the low-level read function of the descriptor.
--- @usage <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.
--- @usage If the limit parameter is ommited, this function uses the nixio
--- buffersize (8192B by default).
--- @usage If the descriptor is non-blocking the iterator may fail with EAGAIN.
--- @usage The iterator can be used as an LTN12 source.
--- @param limit Line limit
--- @return Line-based Iterator
-
---- Create a block-based iterator.
--- @class function
--- @name UnifiedIO.blocksource
--- @usage This function uses the low-level read function of the descriptor.
--- @usage 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.
--- @usage If the limit parameter is ommited, the iterator returns data
--- until an end-of-file, end-of-stream, connection shutdown or similar happens.
--- @usage The iterator will not buffer so it is safe to mix with calls to read.
--- @usage If the descriptor is non-blocking the iterator may fail with EAGAIN.
--- @usage The iterator can be used as an LTN12 source.
--- @param blocksize Advisory blocksize (optional)
--- @param limit Amount of data to consume (optional)
--- @return Block-based Iterator
-
---- Create a sink.
--- This sink will simply write all data that it receives and optionally
--- close the descriptor afterwards.
--- @class function
--- @name UnifiedIO.sink
--- @usage This function uses the writeall function of the descriptor.
--- @usage If the descriptor is non-blocking the sink may fail with EAGAIN.
--- @usage The iterator can be used as an LTN12 sink.
--- @param close_when_done (optional, boolean)
--- @return Sink
-
---- Copy data from the current descriptor to another one.
--- @class function
--- @name UnifiedIO.copy
--- @usage This function uses the blocksource function of the source descriptor
--- and the sink function of the target descriptor.
--- @usage If the limit parameter is ommited, data is copied
--- until an end-of-file, end-of-stream, connection shutdown or similar happens.
--- @usage If the descriptor is non-blocking the function may fail with EAGAIN.
--- @param fdout Target Descriptor
--- @param size Bytes to copy (optional)
--- @return bytes that were successfully written if no error occured
--- @return - reserved for error code -
--- @return - reserved for error message -
--- @return bytes that were successfully written even if an error occured
-
---- Copy data from the current descriptor to another one using kernel-space
--- copying if possible.
--- @class function
--- @name UnifiedIO.copyz
--- @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.
--- @usage If the limit parameter is ommited, data is copied
--- until an end-of-file, end-of-stream, connection shutdown or similar happens.
--- @usage If the descriptor is non-blocking the function may fail with EAGAIN.
--- @param fdout Target Descriptor
--- @param size Bytes to copy (optional)
--- @return bytes that were successfully written if no error occured
--- @return - reserved for error code -
--- @return - reserved for error message -
--- @return bytes that were successfully written even if an error occured
-
---- Close the descriptor.
--- @class function
--- @name UnifiedIO.close
--- @usage If the descriptor is a TLS-socket the underlying descriptor is
--- closed without touching the TLS connection.
--- @return true
\ No newline at end of file
projects / project / luci.git / blobdiff