129 lines
5.8 KiB
Lua
129 lines
5.8 KiB
Lua
--- 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 |