libs/nixio/docsrc/nixio.UnifiedIO.lua

   1 --- Unified high-level I/O utility API for Files, Sockets and TLS-Sockets.
   2 -- These functions are added to the object function tables by doing <strong>
   3 -- require "nixio.util"</strong>, can be used on all nixio IO  Descriptors and
   4 -- are based on the shared low-level read() and write() functions.
   5 -- @cstyle      instance
   6 module "nixio.UnifiedIO"
   7
   8 --- Test whether the I/O-Descriptor is a socket.
   9 -- @class function
  10 -- @name UnifiedIO.is_socket
  11 -- @return      boolean
  12
  13 --- Test whether the I/O-Descriptor is a TLS socket.
  14 -- @class function
  15 -- @name UnifiedIO.is_tls_socket
  16 -- @return      boolean
  17
  18 --- Test whether the I/O-Descriptor is a file.
  19 -- @class function
  20 -- @name UnifiedIO.is_file
  21 -- @return      boolean
  22
  23 --- Read a block of data and wait until all data is available.
  24 -- @class function
  25 -- @name UnifiedIO.readall
  26 -- @usage This function uses the low-level read function of the descriptor.
  27 -- @usage If the length parameter is ommited, this function returns all data
  28 -- that can be read before an end-of-file, end-of-stream, connection shutdown
  29 -- or similar happens.
  30 -- @usage If the descriptor is non-blocking this function may fail with EAGAIN.
  31 -- @param       length  Bytes to read (optional)
  32 -- @return      data that was successfully read if no error occured
  33 -- @return      - reserved for error code -
  34 -- @return      - reserved for error message -
  35 -- @return  data that was successfully read even if an error occured
  36
  37 --- Write a block of data and wait until all data is written.
  38 -- @class function
  39 -- @name UnifiedIO.writeall
  40 -- @usage This function uses the low-level write function of the descriptor.
  41 -- @usage If the descriptor is non-blocking this function may fail with EAGAIN.
  42 -- @param       block   Bytes to write
  43 -- @return      bytes that were successfully written if no error occured
  44 -- @return      - reserved for error code -
  45 -- @return      - reserved for error message -
  46 -- @return  bytes that were successfully written even if an error occured
  47
  48 --- Create a line-based iterator.
  49 -- Lines may end with either \n or \r\n, these control chars are not included
  50 -- in the return value.
  51 -- @class function
  52 -- @name UnifiedIO.linesource
  53 -- @usage This function uses the low-level read function of the descriptor.
  54 -- @usage <strong>Note:</strong> This function uses an internal buffer to read
  55 -- ahead. Do NOT mix calls to read(all) and the returned iterator. If you want
  56 -- to stop reading line-based and want to use the read(all) functions instead
  57 -- you can pass "true" to the iterator which will flush the buffer
  58 -- and return the bufferd data.
  59 -- @usage If the limit parameter is ommited, this function uses the nixio
  60 -- buffersize (8192B by default).
  61 -- @usage If the descriptor is non-blocking the iterator may fail with EAGAIN.
  62 -- @usage The iterator can be used as an LTN12 source.
  63 -- @param       limit   Line limit
  64 -- @return      Line-based Iterator
  65
  66 --- Create a block-based iterator.
  67 -- @class function
  68 -- @name UnifiedIO.blocksource
  69 -- @usage This function uses the low-level read function of the descriptor.
  70 -- @usage The blocksize given is only advisory and to be seen as an upper limit,
  71 -- if an underlying read returns less bytes the chunk is nevertheless returned.
  72 -- @usage If the limit parameter is ommited, the iterator returns data
  73 -- until an end-of-file, end-of-stream, connection shutdown or similar happens.
  74 -- @usage The iterator will not buffer so it is safe to mix with calls to read.
  75 -- @usage If the descriptor is non-blocking the iterator may fail with EAGAIN.
  76 -- @usage The iterator can be used as an LTN12 source.
  77 -- @param       blocksize       Advisory blocksize (optional)
  78 -- @param       limit           Amount of data to consume (optional)
  79 -- @return      Block-based Iterator
  80
  81 --- Create a sink.
  82 -- This sink will simply write all data that it receives and optionally
  83 -- close the descriptor afterwards.
  84 -- @class function
  85 -- @name UnifiedIO.sink
  86 -- @usage This function uses the writeall function of the descriptor.
  87 -- @usage If the descriptor is non-blocking the sink may fail with EAGAIN.
  88 -- @usage The iterator can be used as an LTN12 sink.
  89 -- @param       close_when_done (optional, boolean)
  90 -- @return      Sink
  91
  92 --- Copy data from the current descriptor to another one.
  93 -- @class function
  94 -- @name UnifiedIO.copy
  95 -- @usage This function uses the blocksource function of the source descriptor
  96 -- and the sink function of the target descriptor.
  97 -- @usage If the limit parameter is ommited, data is copied
  98 -- until an end-of-file, end-of-stream, connection shutdown or similar happens.
  99 -- @usage If the descriptor is non-blocking the function may fail with EAGAIN.
 100 -- @param       fdout Target Descriptor
 101 -- @param       size  Bytes to copy (optional)
 102 -- @return      bytes that were successfully written if no error occured
 103 -- @return      - reserved for error code -
 104 -- @return      - reserved for error message -
 105 -- @return  bytes that were successfully written even if an error occured
 106
 107 --- Copy data from the current descriptor to another one using kernel-space
 108 -- copying if possible.
 109 -- @class function
 110 -- @name UnifiedIO.copyz
 111 -- @usage This function uses the sendfile() syscall to copy the data or the
 112 -- blocksource function of the source descriptor and the sink function
 113 -- of the target descriptor as a fallback mechanism.
 114 -- @usage If the limit parameter is ommited, data is copied
 115 -- until an end-of-file, end-of-stream, connection shutdown or similar happens.
 116 -- @usage If the descriptor is non-blocking the function may fail with EAGAIN.
 117 -- @param       fdout Target Descriptor
 118 -- @param       size  Bytes to copy (optional)
 119 -- @return      bytes that were successfully written if no error occured
 120 -- @return      - reserved for error code -
 121 -- @return      - reserved for error message -
 122 -- @return  bytes that were successfully written even if an error occured
 123
 124 --- Close the descriptor.
 125 -- @class function
 126 -- @name UnifiedIO.close
 127 -- @usage       If the descriptor is a TLS-socket the underlying descriptor is
 128 -- closed without touching the TLS connection.
 129 -- @return      true