diff options
author | Jo-Philipp Wich <jow@openwrt.org> | 2014-12-03 15:17:05 +0100 |
---|---|---|
committer | Jo-Philipp Wich <jow@openwrt.org> | 2015-01-08 16:26:20 +0100 |
commit | 1bb4822dca6113f73e3bc89e2acf15935e6f8e92 (patch) | |
tree | 35e16f100466e4e00657199b38bb3d87d52bf73f /libs/luci-lib-nixio/docsrc/nixio.lua | |
parent | 9edd0e46c3f880727738ce8ca6ff1c8b85f99ef4 (diff) |
Rework LuCI build system
* Rename subdirectories to their repective OpenWrt package names
* Make each LuCI module its own standalone package
* Deploy a shared luci.mk which is used by each module Makefile
Signed-off-by: Jo-Philipp Wich <jow@openwrt.org>
Diffstat (limited to 'libs/luci-lib-nixio/docsrc/nixio.lua')
-rw-r--r-- | libs/luci-lib-nixio/docsrc/nixio.lua | 467 |
1 files changed, 467 insertions, 0 deletions
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 |