From baa727de93db009f90d70a80a9861758a24eae77 Mon Sep 17 00:00:00 2001 From: Jo-Philipp Wich Date: Tue, 5 Nov 2019 10:27:59 +0100 Subject: docs: rename documentation folder to docs Signed-off-by: Jo-Philipp Wich --- docs/api/modules/nixio.UnifiedIO.html | 763 ++++++++++++++++++++++++++++++++++ 1 file changed, 763 insertions(+) create mode 100644 docs/api/modules/nixio.UnifiedIO.html (limited to 'docs/api/modules/nixio.UnifiedIO.html') diff --git a/docs/api/modules/nixio.UnifiedIO.html b/docs/api/modules/nixio.UnifiedIO.html new file mode 100644 index 0000000000..6410ffb42e --- /dev/null +++ b/docs/api/modules/nixio.UnifiedIO.html @@ -0,0 +1,763 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

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!

+
+ +
+ + -- cgit v1.2.3