nixio.UnifiedIO.lua 5.8 KB

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