diff options
Diffstat (limited to 'libs/luci-lib-nixio/docsrc')
-rw-r--r-- | libs/luci-lib-nixio/docsrc/CHANGELOG.lua | 29 | ||||
-rw-r--r-- | libs/luci-lib-nixio/docsrc/README.lua | 95 | ||||
-rw-r--r-- | libs/luci-lib-nixio/docsrc/nixio.CryptoHash.lua | 17 | ||||
-rw-r--r-- | libs/luci-lib-nixio/docsrc/nixio.File.lua | 109 | ||||
-rw-r--r-- | libs/luci-lib-nixio/docsrc/nixio.Socket.lua | 170 | ||||
-rw-r--r-- | libs/luci-lib-nixio/docsrc/nixio.TLSContext.lua | 46 | ||||
-rw-r--r-- | libs/luci-lib-nixio/docsrc/nixio.TLSSocket.lua | 73 | ||||
-rw-r--r-- | libs/luci-lib-nixio/docsrc/nixio.UnifiedIO.lua | 129 | ||||
-rw-r--r-- | libs/luci-lib-nixio/docsrc/nixio.bin.lua | 33 | ||||
-rw-r--r-- | libs/luci-lib-nixio/docsrc/nixio.bit.lua | 92 | ||||
-rw-r--r-- | libs/luci-lib-nixio/docsrc/nixio.crypto.lua | 15 | ||||
-rw-r--r-- | libs/luci-lib-nixio/docsrc/nixio.fs.lua | 265 | ||||
-rw-r--r-- | libs/luci-lib-nixio/docsrc/nixio.lua | 467 |
13 files changed, 1540 insertions, 0 deletions
diff --git a/libs/luci-lib-nixio/docsrc/CHANGELOG.lua b/libs/luci-lib-nixio/docsrc/CHANGELOG.lua new file mode 100644 index 0000000000..fb1cf160b6 --- /dev/null +++ b/libs/luci-lib-nixio/docsrc/CHANGELOG.lua @@ -0,0 +1,29 @@ +--- Changes and improvements. +module "CHANGELOG" + +--- Service Release. +-- <ul> +-- <li>Added getifaddrs() function.</li> +-- <li>Added getsockopt(), setsockopt(), getsockname() and getpeername() +-- directly to TLS-socket objects unifying the socket interface.</li> +-- <li>Added support for CyaSSL as cryptographical backend.</li> +-- <li>Added support for x509 certificates in DER format.</li> +-- <li>Added support for splice() in UnifiedIO.copyz().</li> +-- <li>Added interface to inject chunks into UnifiedIO.linesource() buffer.</li> +-- <li>Changed TLS behaviour to explicitely separate servers and clients.</li> +-- <li>Fixed usage of signed datatype breaking Base64 decoding.</li> +-- <li>Fixed namespace clashes for nixio.fs.</li> +-- <li>Fixed splice() support for some exotic C libraries.</li> +-- <li>Reconfigure axTLS cryptographical provider and mark it as obsolete.</li> +-- </ul> +-- @class table +-- @name 0.3 +-- @return ! + +--- Initial Release. +-- <ul> +-- <li>Initial Release</li> +-- </ul> +-- @class table +-- @name 0.2 +-- @return !
\ No newline at end of file diff --git a/libs/luci-lib-nixio/docsrc/README.lua b/libs/luci-lib-nixio/docsrc/README.lua new file mode 100644 index 0000000000..b957a69903 --- /dev/null +++ b/libs/luci-lib-nixio/docsrc/README.lua @@ -0,0 +1,95 @@ +--- General Information. +module "README" + +--- General error handling information. +-- <ul> +-- <li> Most of the functions available in this library may fail. If any error +-- occurs the function returns <strong>nil or false</strong>, an error code +-- (usually errno) and an additional error message text (if avaialable).</li> +-- <li>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.</li> +-- <li>Note that the function documentation does only mention the return values +-- in case of a successful operation.</li> +-- <li>You can find a table of common error numbers and other useful constants +-- like signal numbers in <strong>nixio.const</strong> e.g. nixio.const.EINVAL, +-- nixio.const.SIGTERM, etc. For portability there is a second error constant +-- table <strong>nixio.const_sock</strong> 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.</li> +-- <li>With some exceptions - which are explicitely stated in the function +-- documentation - all blocking functions are signal-protected and will not fail +-- with EINTR.</li> +-- <li>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.</li> +-- </ul> +-- @class table +-- @name Errorhandling +-- @return ! + +--- Function conventions. +-- <br />In general all functions are namend and behave like their POSIX API +-- counterparts - where applicable - applying the following rules: +-- <ul> +-- <li>Functions should be named like the underlying POSIX API function ommiting +-- prefixes or suffixes - especially when placed in an object-context ( +-- lockf -> File:lock, fsync -> File:sync, dup2 -> dup, ...)</li> +-- <li>If you are unclear about the behaviour of a function you should consult +-- your OS API documentation (e.g. the manpages).</li> +-- <li>If the name is significantly different from the POSIX-function, the +-- underlying function(s) are stated in the documentation.</li> +-- <li>Parameters should reflect those of the C-API, buffer length arguments and +-- by-reference parameters should be ommitted for pratical purposes.</li> +-- <li>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 ommiting 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.) </li> +-- <li>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")))</li> +-- </ul> +-- @class table +-- @name Functions +-- @return ! + +--- Platform information. +-- <ul> +-- <li>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.</li> +-- <li>In general all functions which don't have any remarks +-- in their documentation are available on all platforms.</li> +-- <li>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.</li> +-- <li>Some functions might have limitations on some platforms. This should +-- be stated in the documentation. Please also consult your OS API +-- documentation.</li> +-- </ul> +-- @usage Tes +-- @class table +-- @name Platforms +-- @return ! + +--- Cryptography and TLS libraries. +-- <ul> +-- <li>Currently 3 underlying cryptography libraries are supported: openssl, +-- cyassl and axTLS. The name of the library in use is written to +-- <strong>nixio.tls_provider</strong></li> +-- <li>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.</li> +-- <li>As the supported Windows versions are not suitable for embedded devices +-- axTLS is at the moment not supported on Windows.</li> +-- </ul> +-- @usage Tes +-- @class table +-- @name TLS-Crypto +-- @return !
\ No newline at end of file diff --git a/libs/luci-lib-nixio/docsrc/nixio.CryptoHash.lua b/libs/luci-lib-nixio/docsrc/nixio.CryptoHash.lua new file mode 100644 index 0000000000..a08b48d680 --- /dev/null +++ b/libs/luci-lib-nixio/docsrc/nixio.CryptoHash.lua @@ -0,0 +1,17 @@ +--- Cryptographical Hash and HMAC object. +-- @cstyle instance +module "nixio.CryptoHash" + +--- Add another chunk of data to be hashed. +-- @class function +-- @name CryptoHash.update +-- @param chunk Chunk of data +-- @return CryptoHash object (self) + +--- Finalize the hash and return the digest. +-- @class function +-- @name CryptoHash.final +-- @usage You cannot call update on a hash object that was already finalized +-- you can however call final multiple times to get the digest. +-- @return hexdigest +-- @return buffer containing binary digest
\ No newline at end of file diff --git a/libs/luci-lib-nixio/docsrc/nixio.File.lua b/libs/luci-lib-nixio/docsrc/nixio.File.lua new file mode 100644 index 0000000000..368562a2a1 --- /dev/null +++ b/libs/luci-lib-nixio/docsrc/nixio.File.lua @@ -0,0 +1,109 @@ +--- Large File Object. +-- Large file operations are supported up to 52 bits if the Lua number type is +-- double (default). +-- @cstyle instance +module "nixio.File" + +--- Write to the file descriptor. +-- @class function +-- @name File.write +-- @usage <strong>Warning:</strong> It is not guaranteed that all data +-- in the buffer is written at once especially when dealing with pipes. +-- You have to check the return value - the number of bytes actually written - +-- or use the safe IO functions in the high-level IO utility module. +-- @usage Unlike standard Lua indexing the lowest offset and default is 0. +-- @param buffer Buffer holding the data to be written. +-- @param offset Offset to start reading the buffer from. (optional) +-- @param length Length of chunk to read from the buffer. (optional) +-- @return number of bytes written + +--- Read from a file descriptor. +-- @class function +-- @name File.read +-- @usage <strong>Warning:</strong> It is not guaranteed that all requested data +-- is read at once especially when dealing with pipes. +-- You have to check the return value - the length of the buffer actually read - +-- or use the safe IO functions in the high-level IO utility module. +-- @usage The length of the return buffer is limited by the (compile time) +-- nixio buffersize which is <em>nixio.const.buffersize</em> (8192 by default). +-- Any read request greater than that will be safely truncated to this value. +-- @param length Amount of data to read (in Bytes). +-- @return buffer containing data successfully read + +--- Reposition read / write offset of the file descriptor. +-- The seek will be done either from the beginning of the file or relative +-- to the current position or relative to the end. +-- @class function +-- @name File.seek +-- @usage This function calls lseek(). +-- @param offset File Offset +-- @param whence Starting point [<strong>"set"</strong>, "cur", "end"] +-- @return new (absolute) offset position + +--- Return the current read / write offset of the file descriptor. +-- @class function +-- @name File.tell +-- @usage This function calls lseek() with offset 0 from the current position. +-- @return offset position + +--- Synchronizes the file with the storage device. +-- Returns when the file is successfully written to the disk. +-- @class function +-- @name File.sync +-- @usage This function calls fsync() when data_only equals false +-- otherwise fdatasync(), on Windows _commit() is used instead. +-- @usage fdatasync() is only supported by Linux and Solaris. For other systems +-- the <em>data_only</em> parameter is ignored and fsync() is always called. +-- @param data_only Do not synchronize the metadata. (optional, boolean) +-- @return true + +--- Apply or test a lock on the file. +-- @class function +-- @name File.lock +-- @usage This function calls lockf() on POSIX and _locking() on Windows. +-- @usage The "lock" command is blocking, "tlock" is non-blocking, +-- "ulock" unlocks and "test" only tests for the lock. +-- @usage The "test" command is not available on Windows. +-- @usage Locks are by default advisory on POSIX, but mandatory on Windows. +-- @param command Locking Command ["lock", "tlock", "ulock", "test"] +-- @param length Amount of Bytes to lock from current offset (optional) +-- @return true + +--- Get file status and attributes. +-- @class function +-- @name File.stat +-- @param field Only return a specific field, not the whole table (optional) +-- @usage This function calls fstat(). +-- @return Table containing: <ul> +-- <li>atime = Last access timestamp</li> +-- <li>blksize = Blocksize (POSIX only)</li> +-- <li>blocks = Blocks used (POSIX only)</li> +-- <li>ctime = Creation timestamp</li> +-- <li>dev = Device ID</li> +-- <li>gid = Group ID</li> +-- <li>ino = Inode</li> +-- <li>modedec = Mode converted into a decimal number</li> +-- <li>modestr = Mode as string as returned by `ls -l`</li> +-- <li>mtime = Last modification timestamp</li> +-- <li>nlink = Number of links</li> +-- <li>rdev = Device ID (if special file)</li> +-- <li>size = Size in bytes</li> +-- <li>type = ["reg", "dir", "chr", "blk", "fifo", "lnk", "sock"]</li> +-- <li>uid = User ID</li> +-- </ul> + +--- Close the file descriptor. +-- @class function +-- @name File.close +-- @return true + +--- Get the number of the filedescriptor. +-- @class function +-- @name File.fileno +-- @return file descriptor number + +--- (POSIX) Set the blocking mode of the file descriptor. +-- @class function +-- @name File.setblocking +-- @param blocking (boolean) +-- @return true
\ No newline at end of file diff --git a/libs/luci-lib-nixio/docsrc/nixio.Socket.lua b/libs/luci-lib-nixio/docsrc/nixio.Socket.lua new file mode 100644 index 0000000000..7123393bf4 --- /dev/null +++ b/libs/luci-lib-nixio/docsrc/nixio.Socket.lua @@ -0,0 +1,170 @@ +--- Socket Object. +-- Supports IPv4, IPv6 and UNIX (POSIX only) families. +-- @cstyle instance +module "nixio.Socket" + +--- Get the local address of a socket. +-- @class function +-- @name Socket.getsockname +-- @return IP-Address +-- @return Port + +--- Get the peer address of a socket. +-- @class function +-- @name Socket.getpeername +-- @return IP-Address +-- @return Port + +--- Bind the socket to a network address. +-- @class function +-- @name Socket.bind +-- @usage This function calls getaddrinfo() and bind() but NOT listen(). +-- @usage If <em>host</em> is a domain name it will be looked up and bind() +-- tries the IP-Addresses in the order returned by the DNS resolver +-- until the bind succeeds. +-- @usage UNIX sockets ignore the <em>port</em>, +-- and interpret <em>host</em> as a socket path. +-- @param host Host (optional, default: all addresses) +-- @param port Port or service description +-- @return true + +--- Connect the socket to a network address. +-- @class function +-- @name Socket.connect +-- @usage This function calls getaddrinfo() and connect(). +-- @usage If <em>host</em> is a domain name it will be looked up and connect() +-- tries the IP-Addresses in the order returned by the DNS resolver +-- until the connect succeeds. +-- @usage UNIX sockets ignore the <em>port</em>, +-- and interpret <em>host</em> as a socket path. +-- @param host Hostname or IP-Address (optional, default: localhost) +-- @param port Port or service description +-- @return true + +--- Listen for connections on the socket. +-- @class function +-- @name Socket.listen +-- @param backlog Length of queue for pending connections +-- @return true + +--- Accept a connection on the socket. +-- @class function +-- @name Socket.accept +-- @return Socket Object +-- @return Peer IP-Address +-- @return Peer Port + +--- Send a message on the socket specifying the destination. +-- @class function +-- @name Socket.sendto +-- @usage <strong>Warning:</strong> It is not guaranteed that all data +-- in the buffer is written at once. +-- You have to check the return value - the number of bytes actually written - +-- or use the safe IO functions in the high-level IO utility module. +-- @usage Unlike standard Lua indexing the lowest offset and default is 0. +-- @param buffer Buffer holding the data to be written. +-- @param host Target IP-Address +-- @param port Target Port +-- @param offset Offset to start reading the buffer from. (optional) +-- @param length Length of chunk to read from the buffer. (optional) +-- @return number of bytes written + +--- Send a message on the socket. +-- This function is identical to sendto except for the missing destination +-- paramters. See the sendto description for a detailed description. +-- @class function +-- @name Socket.send +-- @param buffer Buffer holding the data to be written. +-- @param offset Offset to start reading the buffer from. (optional) +-- @param length Length of chunk to read from the buffer. (optional) +-- @see Socket.sendto +-- @return number of bytes written + +--- Send a message on the socket (This is an alias for send). +-- See the sendto description for a detailed description. +-- @class function +-- @name Socket.write +-- @param buffer Buffer holding the data to be written. +-- @param offset Offset to start reading the buffer from. (optional) +-- @param length Length of chunk to read from the buffer. (optional) +-- @see Socket.sendto +-- @return number of bytes written + +--- Receive a message on the socket including the senders source address. +-- @class function +-- @name Socket.recvfrom +-- @usage <strong>Warning:</strong> It is not guaranteed that all requested data +-- is read at once. +-- You have to check the return value - the length of the buffer actually read - +-- or use the safe IO functions in the high-level IO utility module. +-- @usage The length of the return buffer is limited by the (compile time) +-- nixio buffersize which is <em>nixio.const.buffersize</em> (8192 by default). +-- Any read request greater than that will be safely truncated to this value. +-- @param length Amount of data to read (in Bytes). +-- @return buffer containing data successfully read +-- @return host IP-Address of the sender +-- @return port Port of the sender + +--- Receive a message on the socket. +-- This function is identical to recvfrom except that it does not return +-- the sender's source address. See the recvfrom description for more details. +-- @class function +-- @name Socket.recv +-- @param length Amount of data to read (in Bytes). +-- @see Socket.recvfrom +-- @return buffer containing data successfully read + +--- Receive a message on the socket (This is an alias for recv). +-- See the recvfrom description for more details. +-- @class function +-- @name Socket.read +-- @param length Amount of data to read (in Bytes). +-- @see Socket.recvfrom +-- @return buffer containing data successfully read + +--- Close the socket. +-- @class function +-- @name Socket.close +-- @return true + +--- Shut down part of a full-duplex connection. +-- @class function +-- @name Socket.shutdown +-- @param how (optional, default: rdwr) ["rdwr", "rd", "wr"] +-- @return true + +--- Get the number of the filedescriptor. +-- @class function +-- @name Socket.fileno +-- @return file descriptor number + +--- Set the blocking mode of the socket. +-- @class function +-- @name Socket.setblocking +-- @param blocking (boolean) +-- @return true + +--- Set a socket option. +-- @class function +-- @name Socket.setopt +-- @param level Level ["socket", "tcp", "ip", "ipv6"] +-- @param option Option ["keepalive", "reuseaddr", "sndbuf", "rcvbuf", +-- "priority", "broadcast", "linger", "sndtimeo", "rcvtimeo", "dontroute", +-- "bindtodevice", "error", "oobinline", "cork" (TCP), "nodelay" (TCP), +-- "mtu" (IP, IPv6), "hdrincl" (IP), "multicast_ttl" (IP), "multicast_loop" +-- (IP, IPv6), "multicast_if" (IP, IPv6), "v6only" (IPv6), "multicast_hops" +-- (IPv6), "add_membership" (IP, IPv6), "drop_membership" (IP, IPv6)] +-- @param value Value +-- @return true + +--- Get a socket option. +-- @class function +-- @name Socket.getopt +-- @param level Level ["socket", "tcp", "ip", "ipv6"] +-- @param option Option ["keepalive", "reuseaddr", "sndbuf", "rcvbuf", +-- "priority", "broadcast", "linger", "sndtimeo", "rcvtimeo", "dontroute", +-- "bindtodevice", "error", "oobinline", "cork" (TCP), "nodelay" (TCP), +-- "mtu" (IP, IPv6), "hdrincl" (IP), "multicast_ttl" (IP), "multicast_loop" +-- (IP, IPv6), "multicast_if" (IP, IPv6), "v6only" (IPv6), "multicast_hops" +-- (IPv6), "add_membership" (IP, IPv6), "drop_membership" (IP, IPv6)] +-- @return Value
\ No newline at end of file diff --git a/libs/luci-lib-nixio/docsrc/nixio.TLSContext.lua b/libs/luci-lib-nixio/docsrc/nixio.TLSContext.lua new file mode 100644 index 0000000000..7cc071195a --- /dev/null +++ b/libs/luci-lib-nixio/docsrc/nixio.TLSContext.lua @@ -0,0 +1,46 @@ +--- Transport Layer Security Context Object. +-- @cstyle instance +module "nixio.TLSContext" + +--- Create a TLS Socket from a socket descriptor. +-- @class function +-- @name TLSContext.create +-- @param socket Socket Object +-- @return TLSSocket Object + +--- Assign a PEM certificate to this context. +-- @class function +-- @name TLSContext.set_cert +-- @usage This function calls SSL_CTX_use_certificate_chain_file(). +-- @param path Certificate File path +-- @return true + +--- Assign a PEM private key to this context. +-- @class function +-- @name TLSContext.set_key +-- @usage This function calls SSL_CTX_use_PrivateKey_file(). +-- @param path Private Key File path +-- @return true + +--- Set the available ciphers for this context. +-- @class function +-- @name TLSContext.set_ciphers +-- @usage This function calls SSL_CTX_set_cipher_list(). +-- @param cipherlist String containing a list of ciphers +-- @return true + +--- Set the verification depth of this context. +-- @class function +-- @name TLSContext.set_verify_depth +-- @usage This function calls SSL_CTX_set_verify_depth(). +-- @param depth Depth +-- @return true + +--- Set the verification flags of this context. +-- @class function +-- @name TLSContext.set_verify +-- @usage This function calls SSL_CTX_set_verify(). +-- @param flag1 First Flag ["none", "peer", "verify_fail_if_no_peer_cert", +-- "client_once"] +-- @param ... More Flags [-"-] +-- @return true
\ No newline at end of file diff --git a/libs/luci-lib-nixio/docsrc/nixio.TLSSocket.lua b/libs/luci-lib-nixio/docsrc/nixio.TLSSocket.lua new file mode 100644 index 0000000000..b932cde0d2 --- /dev/null +++ b/libs/luci-lib-nixio/docsrc/nixio.TLSSocket.lua @@ -0,0 +1,73 @@ +--- TLS Socket Object. +-- TLS Sockets contain the underlying socket and context in the fields +-- "socket" and "context". +-- @cstyle instance +module "nixio.TLSSocket" + +--- Initiate the TLS handshake as client with the server. +-- @class function +-- @name TLSSocket.connect +-- @usage This function calls SSL_connect(). +-- @usage You have to call either connect or accept before transmitting data. +-- @see TLSSocket.accept +-- @return true + +--- Wait for a TLS handshake from a client. +-- @class function +-- @name TLSSocket.accept +-- @usage This function calls SSL_accept(). +-- @usage You have to call either connect or accept before transmitting data. +-- @see TLSSocket.connect +-- @return true + +--- Send a message to the socket. +-- @class function +-- @name TLSSocket.send +-- @usage This function calls SSL_write(). +-- @usage <strong>Warning:</strong> It is not guaranteed that all data +-- in the buffer is written at once. +-- You have to check the return value - the number of bytes actually written - +-- or use the safe IO functions in the high-level IO utility module. +-- @usage Unlike standard Lua indexing the lowest offset and default is 0. +-- @param buffer Buffer holding the data to be written. +-- @param offset Offset to start reading the buffer from. (optional) +-- @param length Length of chunk to read from the buffer. (optional) +-- @return number of bytes written + +--- Send a message on the socket (This is an alias for send). +-- See the send description for a detailed description. +-- @class function +-- @name TLSSocket.write +-- @param buffer Buffer holding the data to be written. +-- @param offset Offset to start reading the buffer from. (optional) +-- @param length Length of chunk to read from the buffer. (optional) +-- @see TLSSocket.send +-- @return number of bytes written + +--- Receive a message on the socket. +-- @class function +-- @name TLSSocket.recv +-- @usage This function calls SSL_read(). +-- @usage <strong>Warning:</strong> It is not guaranteed that all requested data +-- is read at once. +-- You have to check the return value - the length of the buffer actually read - +-- or use the safe IO functions in the high-level IO utility module. +-- @usage The length of the return buffer is limited by the (compile time) +-- nixio buffersize which is <em>nixio.const.buffersize</em> (8192 by default). +-- Any read request greater than that will be safely truncated to this value. +-- @param length Amount of data to read (in Bytes). +-- @return buffer containing data successfully read + +--- Receive a message on the socket (This is an alias for recv). +-- See the recv description for more details. +-- @class function +-- @name TLSSocket.read +-- @param length Amount of data to read (in Bytes). +-- @see TLSSocket.recv +-- @return buffer containing data successfully read + +--- Shut down the TLS connection. +-- @class function +-- @name TLSSocket.shutdown +-- @usage This function calls SSL_shutdown(). +-- @return true
\ No newline at end of file diff --git a/libs/luci-lib-nixio/docsrc/nixio.UnifiedIO.lua b/libs/luci-lib-nixio/docsrc/nixio.UnifiedIO.lua new file mode 100644 index 0000000000..6e407ff2ca --- /dev/null +++ b/libs/luci-lib-nixio/docsrc/nixio.UnifiedIO.lua @@ -0,0 +1,129 @@ +--- Unified high-level I/O utility API for Files, Sockets and TLS-Sockets. +-- These functions are added to the object function tables by doing <strong> +-- require "nixio.util"</strong>, can be used on all nixio IO Descriptors and +-- are based on the shared low-level read() and write() functions. +-- @cstyle instance +module "nixio.UnifiedIO" + +--- Test whether the I/O-Descriptor is a socket. +-- @class function +-- @name UnifiedIO.is_socket +-- @return boolean + +--- Test whether the I/O-Descriptor is a TLS socket. +-- @class function +-- @name UnifiedIO.is_tls_socket +-- @return boolean + +--- Test whether the I/O-Descriptor is a file. +-- @class function +-- @name UnifiedIO.is_file +-- @return boolean + +--- Read a block of data and wait until all data is available. +-- @class function +-- @name UnifiedIO.readall +-- @usage This function uses the low-level read function of the descriptor. +-- @usage If the length parameter is ommited, this function returns all data +-- that can be read before an end-of-file, end-of-stream, connection shutdown +-- or similar happens. +-- @usage If the descriptor is non-blocking this function may fail with EAGAIN. +-- @param length Bytes to read (optional) +-- @return data that was successfully read if no error occured +-- @return - reserved for error code - +-- @return - reserved for error message - +-- @return data that was successfully read even if an error occured + +--- Write a block of data and wait until all data is written. +-- @class function +-- @name UnifiedIO.writeall +-- @usage This function uses the low-level write function of the descriptor. +-- @usage If the descriptor is non-blocking this function may fail with EAGAIN. +-- @param block Bytes to write +-- @return bytes that were successfully written if no error occured +-- @return - reserved for error code - +-- @return - reserved for error message - +-- @return bytes that were successfully written even if an error occured + +--- Create a line-based iterator. +-- Lines may end with either \n or \r\n, these control chars are not included +-- in the return value. +-- @class function +-- @name UnifiedIO.linesource +-- @usage This function uses the low-level read function of the descriptor. +-- @usage <strong>Note:</strong> 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. +-- @usage If the limit parameter is ommited, this function uses the nixio +-- buffersize (8192B by default). +-- @usage If the descriptor is non-blocking the iterator may fail with EAGAIN. +-- @usage The iterator can be used as an LTN12 source. +-- @param limit Line limit +-- @return Line-based Iterator + +--- Create a block-based iterator. +-- @class function +-- @name UnifiedIO.blocksource +-- @usage This function uses the low-level read function of the descriptor. +-- @usage 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. +-- @usage If the limit parameter is ommited, the iterator returns data +-- until an end-of-file, end-of-stream, connection shutdown or similar happens. +-- @usage The iterator will not buffer so it is safe to mix with calls to read. +-- @usage If the descriptor is non-blocking the iterator may fail with EAGAIN. +-- @usage The iterator can be used as an LTN12 source. +-- @param blocksize Advisory blocksize (optional) +-- @param limit Amount of data to consume (optional) +-- @return Block-based Iterator + +--- Create a sink. +-- This sink will simply write all data that it receives and optionally +-- close the descriptor afterwards. +-- @class function +-- @name UnifiedIO.sink +-- @usage This function uses the writeall function of the descriptor. +-- @usage If the descriptor is non-blocking the sink may fail with EAGAIN. +-- @usage The iterator can be used as an LTN12 sink. +-- @param close_when_done (optional, boolean) +-- @return Sink + +--- Copy data from the current descriptor to another one. +-- @class function +-- @name UnifiedIO.copy +-- @usage This function uses the blocksource function of the source descriptor +-- and the sink function of the target descriptor. +-- @usage If the limit parameter is ommited, data is copied +-- until an end-of-file, end-of-stream, connection shutdown or similar happens. +-- @usage If the descriptor is non-blocking the function may fail with EAGAIN. +-- @param fdout Target Descriptor +-- @param size Bytes to copy (optional) +-- @return bytes that were successfully written if no error occured +-- @return - reserved for error code - +-- @return - reserved for error message - +-- @return bytes that were successfully written even if an error occured + +--- Copy data from the current descriptor to another one using kernel-space +-- copying if possible. +-- @class function +-- @name UnifiedIO.copyz +-- @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. +-- @usage If the limit parameter is ommited, data is copied +-- until an end-of-file, end-of-stream, connection shutdown or similar happens. +-- @usage If the descriptor is non-blocking the function may fail with EAGAIN. +-- @param fdout Target Descriptor +-- @param size Bytes to copy (optional) +-- @return bytes that were successfully written if no error occured +-- @return - reserved for error code - +-- @return - reserved for error message - +-- @return bytes that were successfully written even if an error occured + +--- Close the descriptor. +-- @class function +-- @name UnifiedIO.close +-- @usage If the descriptor is a TLS-socket the underlying descriptor is +-- closed without touching the TLS connection. +-- @return true
\ No newline at end of file diff --git a/libs/luci-lib-nixio/docsrc/nixio.bin.lua b/libs/luci-lib-nixio/docsrc/nixio.bin.lua new file mode 100644 index 0000000000..13e125d3cc --- /dev/null +++ b/libs/luci-lib-nixio/docsrc/nixio.bin.lua @@ -0,0 +1,33 @@ +--- Binary operations and conversion. +module "nixio.bin" + +--- Return a hexadecimal ASCII represantation of the content of a buffer. +-- @class function +-- @name hexlify +-- @param buffer Buffer +-- @return representation using characters [0-9a-f] + +--- Return a binary buffer from a hexadecimal ASCII representation. +-- @class function +-- @name unhexlify +-- @param hexvalue representation using characters [0-9a-f] +-- @return binary data + +--- Calculate the CRC32 value of a buffer. +-- @class function +-- @name crc32 +-- @param buffer Buffer +-- @param initial Initial CRC32 value (optional) +-- @return crc32 value + +--- Base64 encode a given buffer. +-- @class function +-- @name b64encode +-- @param buffer Buffer +-- @return base64 encoded buffer + +--- Base64 decode a given buffer. +-- @class function +-- @name b64decode +-- @param buffer Base 64 Encoded data +-- @return binary data
\ No newline at end of file diff --git a/libs/luci-lib-nixio/docsrc/nixio.bit.lua b/libs/luci-lib-nixio/docsrc/nixio.bit.lua new file mode 100644 index 0000000000..6951dd5321 --- /dev/null +++ b/libs/luci-lib-nixio/docsrc/nixio.bit.lua @@ -0,0 +1,92 @@ +--- Bitfield operators and mainpulation functions. +-- Can be used as a drop-in replacement for bitlib. +module "nixio.bit" + +--- Bitwise OR several numbers. +-- @class function +-- @name bor +-- @param oper1 First Operand +-- @param oper2 Second Operand +-- @param ... More Operands +-- @return number + +--- Invert given number. +-- @class function +-- @name bnot +-- @param oper Operand +-- @return number + +--- Bitwise AND several numbers. +-- @class function +-- @name band +-- @param oper1 First Operand +-- @param oper2 Second Operand +-- @param ... More Operands +-- @return number + +--- Bitwise XOR several numbers. +-- @class function +-- @name bxor +-- @param oper1 First Operand +-- @param oper2 Second Operand +-- @param ... More Operands +-- @return number + +--- Left shift a number. +-- @class function +-- @name lshift +-- @param oper number +-- @param shift bits to shift +-- @return number + +--- Right shift a number. +-- @class function +-- @name rshift +-- @param oper number +-- @param shift bits to shift +-- @return number + +--- Arithmetically right shift a number. +-- @class function +-- @name arshift +-- @param oper number +-- @param shift bits to shift +-- @return number + +--- Integer division of 2 or more numbers. +-- @class function +-- @name div +-- @param oper1 Operand 1 +-- @param oper2 Operand 2 +-- @param ... More Operands +-- @return number + +--- Cast a number to the bit-operating range. +-- @class function +-- @name cast +-- @param oper number +-- @return number + +--- Sets one or more flags of a bitfield. +-- @class function +-- @name set +-- @param bitfield Bitfield +-- @param flag1 First Flag +-- @param ... More Flags +-- @return altered bitfield + +--- Unsets one or more flags of a bitfield. +-- @class function +-- @name unset +-- @param bitfield Bitfield +-- @param flag1 First Flag +-- @param ... More Flags +-- @return altered bitfield + +--- Checks whether given flags are set in a bitfield. +-- @class function +-- @name check +-- @param bitfield Bitfield +-- @param flag1 First Flag +-- @param ... More Flags +-- @return true when all flags are set, otherwise false
\ No newline at end of file diff --git a/libs/luci-lib-nixio/docsrc/nixio.crypto.lua b/libs/luci-lib-nixio/docsrc/nixio.crypto.lua new file mode 100644 index 0000000000..158d0fc0bd --- /dev/null +++ b/libs/luci-lib-nixio/docsrc/nixio.crypto.lua @@ -0,0 +1,15 @@ +--- Cryptographical library. +module "nixio.crypto" + +--- Create a hash object. +-- @class function +-- @name nixio.crypto.hash +-- @param algo Algorithm ["sha1", "md5"] +-- @return CryptoHash Object + +--- Create a HMAC object. +-- @class function +-- @name nixio.crypto.hmac +-- @param algo Algorithm ["sha1", "md5"] +-- @param key HMAC-Key +-- @return CryptoHash Object
\ No newline at end of file diff --git a/libs/luci-lib-nixio/docsrc/nixio.fs.lua b/libs/luci-lib-nixio/docsrc/nixio.fs.lua new file mode 100644 index 0000000000..5d08719e96 --- /dev/null +++ b/libs/luci-lib-nixio/docsrc/nixio.fs.lua @@ -0,0 +1,265 @@ +--- Low-level and high-level filesystem manipulation library. +module "nixio.fs" + + +--- Check user's permission on a file. +-- @class function +-- @name nixio.fs.access +-- @param path Path +-- @param mode1 First Mode to check ["f", "r", "w", "x"] +-- @param ... More Modes to check [-"-] +-- @return true + +--- Strip the directory part from a path. +-- @class function +-- @name nixio.fs.basename +-- @usage This function cannot fail and will never return nil. +-- @param path Path +-- @return basename + +--- Strip the base from a path. +-- @class function +-- @name nixio.fs.dirname +-- @usage This function cannot fail and will never return nil. +-- @param path Path +-- @return dirname + +--- Return the cannonicalized absolute pathname. +-- @class function +-- @name nixio.fs.realpath +-- @param path Path +-- @return absolute path + +--- Remove a file or directory. +-- @class function +-- @name nixio.fs.remove +-- @param path Path +-- @return true + +--- Delete a name and - if no links are left - the associated file. +-- @class function +-- @name nixio.fs.unlink +-- @param path Path +-- @return true + +--- Renames a file or directory. +-- @class function +-- @name nixio.fs.rename +-- @param src Source path +-- @param dest Destination path +-- @usage It is normally not possible to rename files accross fileystems. +-- @return true + +--- Remove an empty directory. +-- @class function +-- @name nixio.fs.rmdir +-- @param path Path +-- @return true + +--- Create a new directory. +-- @class function +-- @name nixio.fs.mkdir +-- @param path Path +-- @param mode File mode (optional, see chmod and umask) +-- @see nixio.fs.chmod +-- @see nixio.umask +-- @return true + +--- Change the file mode. +-- @class function +-- @name nixio.fs.chmod +-- @usage Windows only supports setting the write-protection through the +-- "Writable to others" bit. +-- @usage <strong>Notice:</strong> The mode-flag for the functions +-- open, mkdir, mkfifo are affected by the umask. +-- @param path Path +-- @param mode File mode +-- [decimal mode number, "[-r][-w][-xsS][-r][-w][-xsS][-r][-w][-xtT]"] +-- @see nixio.umask +-- @return true + +--- Iterate over the entries of a directory. +-- @class function +-- @name nixio.fs.dir +-- @usage The special entries "." and ".." are omitted. +-- @param path Path +-- @return directory iterator returning one entry per call + +--- Create a hard link. +-- @class function +-- @name nixio.fs.link +-- @usage This function calls link() on POSIX and CreateHardLink() on Windows. +-- @param oldpath Path +-- @param newpath Path +-- @return true + +--- Change file last access and last modification time. +-- @class function +-- @name nixio.fs.utimes +-- @param path Path +-- @param actime Last access timestamp (optional, default: current time) +-- @param mtime Last modification timestamp (optional, default: actime) +-- @return true + +--- Get file status and attributes. +-- @class function +-- @name nixio.fs.stat +-- @param path Path +-- @param field Only return a specific field, not the whole table (optional) +-- @return Table containing: <ul> +-- <li>atime = Last access timestamp</li> +-- <li>blksize = Blocksize (POSIX only)</li> +-- <li>blocks = Blocks used (POSIX only)</li> +-- <li>ctime = Creation timestamp</li> +-- <li>dev = Device ID</li> +-- <li>gid = Group ID</li> +-- <li>ino = Inode</li> +-- <li>modedec = Mode converted into a decimal number</li> +-- <li>modestr = Mode as string as returned by `ls -l`</li> +-- <li>mtime = Last modification timestamp</li> +-- <li>nlink = Number of links</li> +-- <li>rdev = Device ID (if special file)</li> +-- <li>size = Size in bytes</li> +-- <li>type = ["reg", "dir", "chr", "blk", "fifo", "lnk", "sock"]</li> +-- <li>uid = User ID</li> +-- </ul> + +--- Get file status and attributes and do not resolve if target is a symlink. +-- @class function +-- @name nixio.fs.lstat +-- @param path Path +-- @param field Only return a specific field, not the whole table (optional) +-- @see nixio.fs.stat +-- @return Table containing attributes (see stat for a detailed description) + +--- (POSIX) Change owner and group of a file. +-- @class function +-- @name nixio.fs.chown +-- @param path Path +-- @param user User ID or Username (optional) +-- @param group Group ID or Groupname (optional) +-- @return true + +--- (POSIX) Change owner and group of a file and do not resolve +-- if target is a symlink. +-- @class function +-- @name nixio.fs.lchown +-- @param path Path +-- @param user User ID or Username (optional) +-- @param group Group ID or Groupname (optional) +-- @return true + +--- (POSIX) Create a FIFO (named pipe). +-- @class function +-- @name nixio.fs.mkfifo +-- @param path Path +-- @param mode File mode (optional, see chmod and umask) +-- @see nixio.fs.chmod +-- @see nixio.umask +-- @return true + +--- (POSIX) Create a symbolic link. +-- @class function +-- @name nixio.fs.symlink +-- @param oldpath Path +-- @param newpath Path +-- @return true + +--- (POSIX) Read the target of a symbolic link. +-- @class function +-- @name nixio.fs.readlink +-- @param path Path +-- @return target path + +--- (POSIX) Find pathnames matching a pattern. +-- @class function +-- @name nixio.fs.glob +-- @param pattern Pattern +-- @return path iterator +-- @return number of matches + +--- (POSIX) Get filesystem statistics. +-- @class function +-- @name nixio.fs.statvfs +-- @param path Path to any file within the filesystem. +-- @return Table containing: <ul> +-- <li>bavail = available blocks</li> +-- <li>bfree = free blocks</li> +-- <li>blocks = number of fragments</li> +-- <li>frsize = fragment size</li> +-- <li>favail = available inodes</li> +-- <li>ffree = free inodes</li> +-- <li>files = inodes</li> +-- <li>flag = flags</li> +-- <li>fsid = filesystem ID</li> +-- <li>namemax = maximum filename length</li> +-- </ul> + +--- Read the contents of a file into a buffer. +-- @class function +-- @name nixio.fs.readfile +-- @param path Path +-- @param limit Maximum bytes to read (optional) +-- @return file contents + +--- Write a buffer into a file truncating the file first. +-- @class function +-- @name nixio.fs.writefile +-- @param path Path +-- @param data Data to write +-- @return true + +--- Copy data between files. +-- @class function +-- @name nixio.fs.datacopy +-- @param src Source file path +-- @param dest Destination file path +-- @param limit Maximum bytes to copy (optional) +-- @return true + +--- Copy a file, directory or symlink non-recursively preserving file mode, +-- timestamps, owner and group. +-- @class function +-- @name nixio.fs.copy +-- @usage The destination must always be a full destination path e.g. do not +-- omit the basename even if source and destination basename are equal. +-- @param src Source path +-- @param dest Destination path +-- @return true + +--- Rename a file, directory or symlink non-recursively across filesystems. +-- @class function +-- @name nixio.fs.move +-- @usage The destination must always be a full destination path e.g. do not +-- omit the basename even if source and destination basename are equal. +-- @param src Source path +-- @param dest Destination path +-- @return true + +--- Create a directory and all needed parent directories recursively. +-- @class function +-- @name nixio.fs.mkdirr +-- @param dest Destination path +-- @param mode File mode (optional, see chmod and umask) +-- @see nixio.fs.chmod +-- @see nixio.umask +-- @return true + +--- Rename a file, directory or symlink recursively across filesystems. +-- @class function +-- @name nixio.fs.mover +-- @usage The destination must always be a full destination path e.g. do not +-- omit the basename even if source and destination basename are equal. +-- @param src Source path +-- @param dest Destination path +-- @return true + +--- Copy a file, directory or symlink recursively preserving file mode, +-- timestamps, owner and group. +-- @class function +-- @name nixio.fs.copyr +-- @usage The destination must always be a full destination path e.g. do not +-- omit the basename even if source and destination basename are equal. +-- @param src Source path +-- @param dest Destination path +-- @return true
\ No newline at end of file diff --git a/libs/luci-lib-nixio/docsrc/nixio.lua b/libs/luci-lib-nixio/docsrc/nixio.lua new file mode 100644 index 0000000000..1b434d76de --- /dev/null +++ b/libs/luci-lib-nixio/docsrc/nixio.lua @@ -0,0 +1,467 @@ +--- General POSIX IO library. +module "nixio" + +--- Look up a hostname and service via DNS. +-- @class function +-- @name nixio.getaddrinfo +-- @param host hostname to lookup (optional) +-- @param family address family [<strong>"any"</strong>, "inet", "inet6"] +-- @param service service name or port (optional) +-- @return Table containing one or more tables containing: <ul> +-- <li>family = ["inet", "inet6"]</li> +-- <li>socktype = ["stream", "dgram", "raw"]</li> +-- <li>address = Resolved IP-Address</li> +-- <li>port = Resolved Port (if service was given)</li> +-- </ul> + +--- Reverse look up an IP-Address via DNS. +-- @class function +-- @name nixio.getnameinfo +-- @param ipaddr IPv4 or IPv6-Address +-- @return FQDN + +--- (Linux, BSD) Get a list of available network interfaces and their addresses. +-- @class function +-- @name nixio.getifaddrs +-- @return Table containing one or more tables containing: <ul> +-- <li>name = Interface Name</li> +-- <li>family = ["inet", "inet6", "packet"]</li> +-- <li>addr = Interface Address (IPv4, IPv6, MAC, ...)</li> +-- <li>broadaddr = Broadcast Address</li> +-- <li>dstaddr = Destination Address (Point-to-Point)</li> +-- <li>netmask = Netmask (if available)</li> +-- <li>prefix = Prefix (if available)</li> +-- <li>flags = Table of interface flags (up, multicast, loopback, ...)</li> +-- <li>data = Statistics (Linux, "packet"-family)</li> +-- <li>hatype = Hardware Type Identifier (Linix, "packet"-family)</li> +-- <li>ifindex = Interface Index (Linux, "packet"-family)</li> +-- </ul> + +--- Get protocol entry by name. +-- @usage This function returns nil if the given protocol is unknown. +-- @class function +-- @name nixio.getprotobyname +-- @param name protocol name to lookup +-- @return Table containing the following fields: <ul> +-- <li>name = Protocol Name</li> +-- <li>proto = Protocol Number</li> +-- <li>aliases = Table of alias names</li> +-- </ul> + +--- Get protocol entry by number. +-- @usage This function returns nil if the given protocol is unknown. +-- @class function +-- @name nixio.getprotobynumber +-- @param proto protocol number to lookup +-- @return Table containing the following fields: <ul> +-- <li>name = Protocol Name</li> +-- <li>proto = Protocol Number</li> +-- <li>aliases = Table of alias names</li> +-- </ul> + +--- Get all or a specifc proto entry. +-- @class function +-- @name nixio.getproto +-- @param proto protocol number or name to lookup (optional) +-- @return Table (or if no parameter is given, a table of tables) +-- containing the following fields: <ul> +-- <li>name = Protocol Name</li> +-- <li>proto = Protocol Number</li> +-- <li>aliases = Table of alias names</li> +-- </ul> + +--- Create a new socket and bind it to a network address. +-- This function is a shortcut for calling nixio.socket and then bind() +-- on the socket object. +-- @usage This functions calls getaddrinfo(), socket(), +-- setsockopt() and bind() but NOT listen(). +-- @usage The <em>reuseaddr</em>-option is automatically set before binding. +-- @class function +-- @name nixio.bind +-- @param host Hostname or IP-Address (optional, default: all addresses) +-- @param port Port or service description +-- @param family Address family [<strong>"any"</strong>, "inet", "inet6"] +-- @param socktype Socket Type [<strong>"stream"</strong>, "dgram"] +-- @return Socket Object + +--- Create a new socket and connect to a network address. +-- This function is a shortcut for calling nixio.socket and then connect() +-- on the socket object. +-- @usage This functions calls getaddrinfo(), socket() and connect(). +-- @class function +-- @name nixio.connect +-- @param host Hostname or IP-Address (optional, default: localhost) +-- @param port Port or service description +-- @param family Address family [<strong>"any"</strong>, "inet", "inet6"] +-- @param socktype Socket Type [<strong>"stream"</strong>, "dgram"] +-- @return Socket Object + +--- Open a file. +-- @class function +-- @name nixio.open +-- @usage Although this function also supports the traditional fopen() +-- file flags it does not create a file stream but uses the open() syscall. +-- @param path Filesystem path to open +-- @param flags Flag string or number (see open_flags). +-- [<strong>"r"</strong>, "r+", "w", "w+", "a", "a+"] +-- @param mode File mode for newly created files (see chmod, umask). +-- @see nixio.umask +-- @see nixio.open_flags +-- @return File Object + +--- Generate flags for a call to open(). +-- @class function +-- @name nixio.open_flags +-- @usage This function cannot fail and will never return nil. +-- @usage The "nonblock" and "ndelay" flags are aliases. +-- @usage The "nonblock", "ndelay" and "sync" flags are no-ops on Windows. +-- @param flag1 First Flag ["append", "creat", "excl", "nonblock", "ndelay", +-- "sync", "trunc", "rdonly", "wronly", "rdwr"] +-- @param ... More Flags [-"-] +-- @return flag to be used as second paramter to open + +--- Duplicate a file descriptor. +-- @class function +-- @name nixio.dup +-- @usage This funcation calls dup2() if <em>newfd</em> is set, otherwise dup(). +-- @param oldfd Old descriptor [File Object, Socket Object (POSIX only)] +-- @param newfd New descriptor to serve as copy (optional) +-- @return File Object of new descriptor + +--- Create a pipe. +-- @class function +-- @name nixio.pipe +-- @return File Object of the read end +-- @return File Object of the write end + +--- Get the last system error code. +-- @class function +-- @name nixio.errno +-- @return Error code + +--- Get the error message for the corresponding error code. +-- @class function +-- @name nixio.strerror +-- @param errno System error code +-- @return Error message + +--- Sleep for a specified amount of time. +-- @class function +-- @usage Not all systems support nanosecond precision but you can expect +-- to have at least maillisecond precision. +-- @usage This function is not signal-protected and may fail with EINTR. +-- @param seconds Seconds to wait (optional) +-- @param nanoseconds Nanoseconds to wait (optional) +-- @name nixio.nanosleep +-- @return true + +--- Generate events-bitfield or parse revents-bitfield for poll. +-- @class function +-- @name nixio.poll_flags +-- @param mode1 revents-Flag bitfield returned from poll to parse OR +-- ["in", "out", "err", "pri" (POSIX), "hup" (POSIX), "nval" (POSIX)] +-- @param ... More mode strings for generating the flag [-"-] +-- @see nixio.poll +-- @return table with boolean fields reflecting the mode parameter +-- <strong>OR</strong> bitfield to use for the events-Flag field + +--- Wait for some event on a file descriptor. +-- poll() sets the revents-field of the tables provided by fds to a bitfield +-- indicating the events that occured. +-- @class function +-- @usage This function works in-place on the provided table and only +-- writes the revents field, you can use other fields on your demand. +-- @usage All metamethods on the tables provided as fds are ignored. +-- @usage The revents-fields are not reset when the call times out. +-- You have to check the first return value to be 0 to handle this case. +-- @usage If you want to wait on a TLS-Socket you have to use the underlying +-- socket instead. +-- @usage On Windows poll is emulated through select(), can only be used +-- on socket descriptors and cannot take more than 64 descriptors per call. +-- @usage This function is not signal-protected and may fail with EINTR. +-- @param fds Table containing one or more tables containing <ul> +-- <li> fd = I/O Descriptor [Socket Object, File Object (POSIX)]</li> +-- <li> events = events to wait for (bitfield generated with poll_flags)</li> +-- </ul> +-- @param timeout Timeout in milliseconds +-- @name nixio.poll +-- @see nixio.poll_flags +-- @return number of ready IO descriptors +-- @return the fds-table with revents-fields set + +--- (POSIX) Clone the current process. +-- @class function +-- @name nixio.fork +-- @return the child process id for the parent process, 0 for the child process + +--- (POSIX) Send a signal to one or more processes. +-- @class function +-- @name nixio.kill +-- @param target Target process of process group. +-- @param signal Signal to send +-- @return true + +--- (POSIX) Get the parent process id of the current process. +-- @class function +-- @name nixio.getppid +-- @return parent process id + +--- (POSIX) Get the user id of the current process. +-- @class function +-- @name nixio.getuid +-- @return process user id + +--- (POSIX) Get the group id of the current process. +-- @class function +-- @name nixio.getgid +-- @return process group id + +--- (POSIX) Set the group id of the current process. +-- @class function +-- @name nixio.setgid +-- @param gid New Group ID +-- @return true + +--- (POSIX) Set the user id of the current process. +-- @class function +-- @name nixio.setuid +-- @param gid New User ID +-- @return true + +--- (POSIX) Change priority of current process. +-- @class function +-- @name nixio.nice +-- @param nice Nice Value +-- @return true + +--- (POSIX) Create a new session and set the process group ID. +-- @class function +-- @name nixio.setsid +-- @return session id + +--- (POSIX) Wait for a process to change state. +-- @class function +-- @name nixio.waitpid +-- @usage If the "nohang" is given this function becomes non-blocking. +-- @param pid Process ID (optional, default: any childprocess) +-- @param flag1 Flag (optional) ["nohang", "untraced", "continued"] +-- @param ... More Flags [-"-] +-- @return process id of child or 0 if no child has changed state +-- @return ["exited", "signaled", "stopped"] +-- @return [exit code, terminate signal, stop signal] + +--- (POSIX) Get process times. +-- @class function +-- @name nixio.times +-- @return Table containing: <ul> +-- <li>utime = user time</li> +-- <li>utime = system time</li> +-- <li>cutime = children user time</li> +-- <li>cstime = children system time</li> +-- </ul> + +--- (POSIX) Get information about current system and kernel. +-- @class function +-- @name nixio.uname +-- @return Table containing: <ul> +-- <li>sysname = operating system</li> +-- <li>nodename = network name (usually hostname)</li> +-- <li>release = OS release</li> +-- <li>version = OS version</li> +-- <li>machine = hardware identifier</li> +-- </ul> + +--- Change the working directory. +-- @class function +-- @name nixio.chdir +-- @param path New working directory +-- @return true + +--- Ignore or use set the default handler for a signal. +-- @class function +-- @name nixio.signal +-- @param signal Signal +-- @param handler ["ign", "dfl"] +-- @return true + +--- Get the ID of the current process. +-- @class function +-- @name nixio.getpid +-- @return process id + +--- Get the current working directory. +-- @class function +-- @name nixio.getcwd +-- @return workign directory + +--- Get the current environment table or a specific environment variable. +-- @class function +-- @name nixio.getenv +-- @param variable Variable (optional) +-- @return environment table or single environment variable + +--- Set or unset a environment variable. +-- @class function +-- @name nixio.setenv +-- @usage The environment variable will be unset if value is ommited. +-- @param variable Variable +-- @param value Value (optional) +-- @return true + +--- Execute a file to replace the current process. +-- @class function +-- @name nixio.exec +-- @usage The name of the executable is automatically passed as argv[0] +-- @usage This function does not return on success. +-- @param executable Executable +-- @param ... Parameters + +--- Invoke the shell and execute a file to replace the current process. +-- @class function +-- @name nixio.execp +-- @usage The name of the executable is automatically passed as argv[0] +-- @usage This function does not return on success. +-- @param executable Executable +-- @param ... Parameters + +--- Execute a file with a custom environment to replace the current process. +-- @class function +-- @name nixio.exece +-- @usage The name of the executable is automatically passed as argv[0] +-- @usage This function does not return on success. +-- @param executable Executable +-- @param arguments Argument Table +-- @param environment Environment Table (optional) + +--- Sets the file mode creation mask. +-- @class function +-- @name nixio.umask +-- @param mask New creation mask (see chmod for format specifications) +-- @return the old umask as decimal mode number +-- @return the old umask as mode string + +--- (Linux) Get overall system statistics. +-- @class function +-- @name nixio.sysinfo +-- @return Table containing: <ul> +-- <li>uptime = system uptime in seconds</li> +-- <li>loads = {loadavg1, loadavg5, loadavg15}</li> +-- <li>totalram = total RAM</li> +-- <li>freeram = free RAM</li> +-- <li>sharedram = shared RAM</li> +-- <li>bufferram = buffered RAM</li> +-- <li>totalswap = total SWAP</li> +-- <li>freeswap = free SWAP</li> +-- <li>procs = number of running processes</li> +-- </ul> + +--- Create a new socket. +-- @class function +-- @name nixio.socket +-- @param domain Domain ["inet", "inet6", "unix"] +-- @param type Type ["stream", "dgram", "raw"] +-- @return Socket Object + +--- (POSIX) Send data from a file to a socket in kernel-space. +-- @class function +-- @name nixio.sendfile +-- @param socket Socket Object +-- @param file File Object +-- @param length Amount of data to send (in Bytes). +-- @return bytes sent + +--- (Linux) Send data from / to a pipe in kernel-space. +-- @class function +-- @name nixio.splice +-- @param fdin Input I/O descriptor +-- @param fdout Output I/O descriptor +-- @param length Amount of data to send (in Bytes). +-- @param flags (optional, bitfield generated by splice_flags) +-- @see nixio.splice_flags +-- @return bytes sent + +--- (Linux) Generate a flag bitfield for a call to splice. +-- @class function +-- @name nixio.splice_flags +-- @param flag1 First Flag ["move", "nonblock", "more"] +-- @param ... More flags [-"-] +-- @see nixio.splice +-- @return Flag bitfield + +--- (POSIX) Open a connection to the system logger. +-- @class function +-- @name nixio.openlog +-- @param ident Identifier +-- @param flag1 Flag 1 ["cons", "nowait", "pid", "perror", "ndelay", "odelay"] +-- @param ... More flags [-"-] + +--- (POSIX) Close the connection to the system logger. +-- @class function +-- @name nixio.closelog + +--- (POSIX) Write a message to the system logger. +-- @class function +-- @name nixio.syslog +-- @param priority Priority ["emerg", "alert", "crit", "err", "warning", +-- "notice", "info", "debug"] +-- @param message + +--- (POSIX) Set the logmask of the system logger for current process. +-- @class function +-- @name nixio.setlogmask +-- @param priority Priority ["emerg", "alert", "crit", "err", "warning", +-- "notice", "info", "debug"] + +--- (POSIX) Encrypt a user password. +-- @class function +-- @name nixio.crypt +-- @param key Key +-- @param salt Salt +-- @return password hash + +--- (POSIX) Get all or a specific user group. +-- @class function +-- @name nixio.getgr +-- @param group Group ID or groupname (optional) +-- @return Table containing: <ul> +-- <li>name = Group Name</li> +-- <li>gid = Group ID</li> +-- <li>passwd = Password</li> +-- <li>mem = {Member #1, Member #2, ...}</li> +-- </ul> + +--- (POSIX) Get all or a specific user account. +-- @class function +-- @name nixio.getpw +-- @param user User ID or username (optional) +-- @return Table containing: <ul> +-- <li>name = Name</li> +-- <li>uid = ID</li> +-- <li>gid = Group ID</li> +-- <li>passwd = Password</li> +-- <li>dir = Home directory</li> +-- <li>gecos = Information</li> +-- <li>shell = Shell</li> +-- </ul> + +--- (Linux, Solaris) Get all or a specific shadow password entry. +-- @class function +-- @name nixio.getsp +-- @param user username (optional) +-- @return Table containing: <ul> +-- <li>namp = Name</li> +-- <li>expire = Expiration Date</li> +-- <li>flag = Flags</li> +-- <li>inact = Inactivity Date</li> +-- <li>lstchg = Last change</li> +-- <li>max = Maximum</li> +-- <li>min = Minimum</li> +-- <li>warn = Warning</li> +-- <li>pwdp = Password Hash</li> +-- </ul> + +--- Create a new TLS context. +-- @class function +-- @name nixio.tls +-- @param mode TLS-Mode ["client", "server"] +-- @return TLSContext Object |