luci/libs/luci-lib-nixio/docsrc

--- General Information.
module "nixio.README"

--- General error handling information.
--

--
• Most of the functions available in this library may fail. If any error
  -- occurs the function returns nil or false, an error code
  -- (usually errno) and an additional error message text (if avaialable).

--
• At the moment false is only returned when a non-blocking I/O function
  -- fails with EAGAIN, EWOULDBLOCK or WSAEWOULDBLOCK for any others nil is
  -- returned as first parameter. Therefore you can use false to write portable
  -- non-blocking I/O applications.

--
• Note that the function documentation does only mention the return values
  -- in case of a successful operation.

--
• You can find a table of common error numbers and other useful constants
  -- like signal numbers in nixio.const e.g. nixio.const.EINVAL,
  -- nixio.const.SIGTERM, etc. For portability there is a second error constant
  -- table nixio.const_sock for socket error codes. This might
  -- be important if you are dealing with Windows applications, on POSIX however
  -- const_sock is just an alias for const.

--
• With some exceptions - which are explicitly stated in the function
  -- documentation - all blocking functions are signal-protected and will not fail
  -- with EINTR.

--
• On POSIX the SIGPIPE signal will be set to ignore upon initialization.
  -- You should restore the default behaviour or set a custom signal handler
  -- in your program after loading nixio if you need this behaviour.

--

-- @class table
-- @name Errorhandling
-- @return !

--- Function conventions.
--
In general all functions are namend and behave like their POSIX API
-- counterparts - where applicable - applying the following rules:
--

--
• Functions should be named like the underlying POSIX API function omitting
  -- prefixes or suffixes - especially when placed in an object-context (
  -- lockf -> File:lock, fsync -> File:sync, dup2 -> dup, ...)

--
• If you are unclear about the behaviour of a function you should consult
  -- your OS API documentation (e.g. the manpages).

--
• If the name is significantly different from the POSIX-function, the
  -- underlying function(s) are stated in the documentation.

--
• Parameters should reflect those of the C-API, buffer length arguments and
  -- by-reference parameters should be omitted for practical purposes.

--
• If a C function accepts a bitfield as parameter, it should be translated
  -- into lower case string flags representing the flags if the bitfield is the
  -- last parameter and also omitting prefixes or suffixes. (e.g. waitpid
  -- (pid, &s, WNOHANG | WUNTRACED) -> waitpid(pid, "nohang", "untraced"),
  -- getsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &opt, sizeof(opt)) ->
  -- Socket:getopt("socket", "reuseaddr"), etc.)

--
• If it is not applicable to provide a string representation of the
  -- bitfield a bitfield generator helper is provided. It is named FUNCTION_flags.
  -- (open("/tmp/test", O_RDONLY | O_NONBLOCK) -> open("/tmp/test", open_flags(
  -- "rdonly", "nonblock")))

--

-- @class table
-- @name Functions
-- @return !

--- Platform information.
--

--
• The minimum platform requirements are a decent POSIX 2001 support.
  -- Builds are more or less tested on Linux, Solaris and FreeBSD. Builds for
  -- Windows XP SP1 and later can be compiled with MinGW either from Windows
  -- itself or using the MinGW cross-compiler. Earlier versions of Windows are not
  -- supported.

--
• In general all functions which don't have any remarks
  -- in their documentation are available on all platforms.

--
• Functions with a (POSIX), (Linux) or similar prefix are only available
  -- on these specific platforms. Same appplies to parameters of functions
  -- with a similar suffix.

--
• Some functions might have limitations on some platforms. This should
  -- be stated in the documentation. Please also consult your OS API
  -- documentation.

--

-- @usage Tes
-- @class table
-- @name Platforms
-- @return !

--- Cryptography and TLS libraries.
--

--
• Currently 3 underlying cryptography libraries are supported: openssl,
  -- cyassl and axTLS. The name of the library in use is written to
  -- nixio.tls_provider

--
• You should whenever possible use openssl or cyassl as axTLS has only
  -- limited support. It does not provide support for non-blocking sockets and
  -- is probably less audited than the other ones.

--
• As the supported Windows versions are not suitable for embedded devices
  -- axTLS is at the moment not supported on Windows.

--

-- @usage Tes
-- @class table
-- @name TLS-Crypto
-- @return !