2
0

README.lua 4.6 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889909192939495
  1. --- General Information.
  2. module "nixio.README"
  3. --- General error handling information.
  4. -- <ul>
  5. -- <li> Most of the functions available in this library may fail. If any error
  6. -- occurs the function returns <strong>nil or false</strong>, an error code
  7. -- (usually errno) and an additional error message text (if avaialable).</li>
  8. -- <li>At the moment false is only returned when a non-blocking I/O function
  9. -- fails with EAGAIN, EWOULDBLOCK or WSAEWOULDBLOCK for any others nil is
  10. -- returned as first parameter. Therefore you can use false to write portable
  11. -- non-blocking I/O applications.</li>
  12. -- <li>Note that the function documentation does only mention the return values
  13. -- in case of a successful operation.</li>
  14. -- <li>You can find a table of common error numbers and other useful constants
  15. -- like signal numbers in <strong>nixio.const</strong> e.g. nixio.const.EINVAL,
  16. -- nixio.const.SIGTERM, etc. For portability there is a second error constant
  17. -- table <strong>nixio.const_sock</strong> for socket error codes. This might
  18. -- be important if you are dealing with Windows applications, on POSIX however
  19. -- const_sock is just an alias for const.</li>
  20. -- <li>With some exceptions - which are explicitly stated in the function
  21. -- documentation - all blocking functions are signal-protected and will not fail
  22. -- with EINTR.</li>
  23. -- <li>On POSIX the SIGPIPE signal will be set to ignore upon initialization.
  24. -- You should restore the default behaviour or set a custom signal handler
  25. -- in your program after loading nixio if you need this behaviour.</li>
  26. -- </ul>
  27. -- @class table
  28. -- @name Errorhandling
  29. -- @return !
  30. --- Function conventions.
  31. -- <br />In general all functions are namend and behave like their POSIX API
  32. -- counterparts - where applicable - applying the following rules:
  33. -- <ul>
  34. -- <li>Functions should be named like the underlying POSIX API function omitting
  35. -- prefixes or suffixes - especially when placed in an object-context (
  36. -- lockf -> File:lock, fsync -> File:sync, dup2 -> dup, ...)</li>
  37. -- <li>If you are unclear about the behaviour of a function you should consult
  38. -- your OS API documentation (e.g. the manpages).</li>
  39. -- <li>If the name is significantly different from the POSIX-function, the
  40. -- underlying function(s) are stated in the documentation.</li>
  41. -- <li>Parameters should reflect those of the C-API, buffer length arguments and
  42. -- by-reference parameters should be omitted for practical purposes.</li>
  43. -- <li>If a C function accepts a bitfield as parameter, it should be translated
  44. -- into lower case string flags representing the flags if the bitfield is the
  45. -- last parameter and also omitting prefixes or suffixes. (e.g. waitpid
  46. -- (pid, &s, WNOHANG | WUNTRACED) -> waitpid(pid, "nohang", "untraced"),
  47. -- getsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt)) ->
  48. -- Socket:getopt("socket", "reuseaddr"), etc.) </li>
  49. -- <li>If it is not applicable to provide a string representation of the
  50. -- bitfield a bitfield generator helper is provided. It is named FUNCTION_flags.
  51. -- (open("/tmp/test", O_RDONLY | O_NONBLOCK) -> open("/tmp/test", open_flags(
  52. -- "rdonly", "nonblock")))</li>
  53. -- </ul>
  54. -- @class table
  55. -- @name Functions
  56. -- @return !
  57. --- Platform information.
  58. -- <ul>
  59. -- <li>The minimum platform requirements are a decent POSIX 2001 support.
  60. -- Builds are more or less tested on Linux, Solaris and FreeBSD. Builds for
  61. -- Windows XP SP1 and later can be compiled with MinGW either from Windows
  62. -- itself or using the MinGW cross-compiler. Earlier versions of Windows are not
  63. -- supported.</li>
  64. -- <li>In general all functions which don't have any remarks
  65. -- in their documentation are available on all platforms.</li>
  66. -- <li>Functions with a (POSIX), (Linux) or similar prefix are only available
  67. -- on these specific platforms. Same appplies to parameters of functions
  68. -- with a similar suffix.</li>
  69. -- <li>Some functions might have limitations on some platforms. This should
  70. -- be stated in the documentation. Please also consult your OS API
  71. -- documentation.</li>
  72. -- </ul>
  73. -- @usage Tes
  74. -- @class table
  75. -- @name Platforms
  76. -- @return !
  77. --- Cryptography and TLS libraries.
  78. -- <ul>
  79. -- <li>Currently 3 underlying cryptography libraries are supported: openssl,
  80. -- cyassl and axTLS. The name of the library in use is written to
  81. -- <strong>nixio.tls_provider</strong></li>
  82. -- <li>You should whenever possible use openssl or cyassl as axTLS has only
  83. -- limited support. It does not provide support for non-blocking sockets and
  84. -- is probably less audited than the other ones.</li>
  85. -- <li>As the supported Windows versions are not suitable for embedded devices
  86. -- axTLS is at the moment not supported on Windows.</li>
  87. -- </ul>
  88. -- @usage Tes
  89. -- @class table
  90. -- @name TLS-Crypto
  91. -- @return !