From 2e6118888156b66d8a84e6487de12d5ba88a6a6e Mon Sep 17 00:00:00 2001 From: Jo-Philipp Wich Date: Tue, 1 Sep 2015 12:19:27 +0200 Subject: Add generated documentation to repository Signed-off-by: Jo-Philipp Wich --- doc/modules/nixio.html | 2373 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2373 insertions(+) create mode 100644 doc/modules/nixio.html (limited to 'doc/modules/nixio.html') diff --git a/doc/modules/nixio.html b/doc/modules/nixio.html new file mode 100644 index 0000000000..8b0f84b1af --- /dev/null +++ b/doc/modules/nixio.html @@ -0,0 +1,2373 @@ + + + + Reference + + + + + +
+ +
+ +
+
+
+ +
+ + + +
+ +

Class nixio

+ +

+ General POSIX IO library.

+ + + + + + + +

Functions

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
bind (host, port, family, socktype) + Create a new socket and bind it to a network address.
chdir (path) + Change the working directory.
closelog () + (POSIX) Close the connection to the system logger.
connect (host, port, family, socktype) + Create a new socket and connect to a network address.
crypt (key, salt) + (POSIX) Encrypt a user password.
dup (oldfd, newfd) + Duplicate a file descriptor.
errno () + Get the last system error code.
exec (executable, ...) + Execute a file to replace the current process.
exece (executable, arguments, environment) + Execute a file with a custom environment to replace the current process.
execp (executable, ...) + Invoke the shell and execute a file to replace the current process.
fork () + (POSIX) Clone the current process.
getaddrinfo (host, family, service) + Look up a hostname and service via DNS.
getcwd () + Get the current working directory.
getenv (variable) + Get the current environment table or a specific environment variable.
getgid () + (POSIX) Get the group id of the current process.
getgr (group) + (POSIX) Get all or a specific user group.
getifaddrs () + (Linux, BSD) Get a list of available network interfaces and their addresses.
getnameinfo (ipaddr) + Reverse look up an IP-Address via DNS.
getpid () + Get the ID of the current process.
getppid () + (POSIX) Get the parent process id of the current process.
getproto (proto) + Get all or a specifc proto entry.
getprotobyname (name) + Get protocol entry by name.
getprotobynumber (proto) + Get protocol entry by number.
getpw (user) + (POSIX) Get all or a specific user account.
getsp (user) + (Linux, Solaris) Get all or a specific shadow password entry.
getuid () + (POSIX) Get the user id of the current process.
kill (target, signal) + (POSIX) Send a signal to one or more processes.
nanosleep (seconds, nanoseconds) + Sleep for a specified amount of time.
nice (nice) + (POSIX) Change priority of current process.
open (path, flags, mode) + Open a file.
open_flags (flag1, ...) + Generate flags for a call to open().
openlog (ident, flag1, ...) + (POSIX) Open a connection to the system logger.
pipe () + Create a pipe.
poll (fds, timeout) + Wait for some event on a file descriptor.
poll_flags (mode1, ...) + Generate events-bitfield or parse revents-bitfield for poll.
sendfile (socket, file, length) + (POSIX) Send data from a file to a socket in kernel-space.
setenv (variable, value) + Set or unset a environment variable.
setgid (gid) + (POSIX) Set the group id of the current process.
setlogmask (priority) + (POSIX) Set the logmask of the system logger for current process.
setsid () + (POSIX) Create a new session and set the process group ID.
setuid (gid) + (POSIX) Set the user id of the current process.
signal (signal, handler) + Ignore or use set the default handler for a signal.
socket (domain, type) + Create a new socket.
splice (fdin, fdout, length, flags) + (Linux) Send data from / to a pipe in kernel-space.
splice_flags (flag1, ...) + (Linux) Generate a flag bitfield for a call to splice.
strerror (errno) + Get the error message for the corresponding error code.
sysinfo () + (Linux) Get overall system statistics.
syslog (priority) + (POSIX) Write a message to the system logger.
times () + (POSIX) Get process times.
tls (mode) + Create a new TLS context.
umask (mask) + Sets the file mode creation mask.
uname () + (POSIX) Get information about current system and kernel.
waitpid (pid, flag1, ...) + (POSIX) Wait for a process to change state.
+ + + + + + +
+
+ + +

Functions

+
+ + + +
bind (host, port, family, socktype)
+
+ + 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. + + +

Parameters

+
    + +
  • + host: Hostname or IP-Address (optional, default: all addresses) +
    • + +
  • + port: Port or service description +
    • + +
  • + family: Address family ["any", "inet", "inet6"] +
    • + +
  • + socktype: Socket Type ["stream", "dgram"] +
    • + +
+ + + + +

Usage

+
    + +
  • This functions calls getaddrinfo(), socket(), + setsockopt() and bind() but NOT listen(). + +
  • The reuseaddr-option is automatically set before binding. + +
+ + + +

Return value:

+Socket Object + + + +
+ + + + +
chdir (path)
+
+ + Change the working directory. + + +

Parameters

+
    + +
  • + path: New working directory +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
closelog ()
+
+ + (POSIX) Close the connection to the system logger. + + + + + + + + + +
+ + + + +
connect (host, port, family, socktype)
+
+ + 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. + + +

Parameters

+
    + +
  • + host: Hostname or IP-Address (optional, default: localhost) +
    • + +
  • + port: Port or service description +
    • + +
  • + family: Address family ["any", "inet", "inet6"] +
    • + +
  • + socktype: Socket Type ["stream", "dgram"] +
    • + +
+ + + + +

Usage:

+This functions calls getaddrinfo(), socket() and connect(). + + + +

Return value:

+Socket Object + + + +
+ + + + +
crypt (key, salt)
+
+ + (POSIX) Encrypt a user password. + + +

Parameters

+
    + +
  • + key: Key +
    • + +
  • + salt: Salt +
    • + +
+ + + + + + +

Return value:

+password hash + + + +
+ + + + +
dup (oldfd, newfd)
+
+ + Duplicate a file descriptor. + + +

Parameters

+
    + +
  • + oldfd: Old descriptor [File Object, Socket Object (POSIX only)] +
    • + +
  • + newfd: New descriptor to serve as copy (optional) +
    • + +
+ + + + +

Usage:

+This funcation calls dup2() if newfd is set, otherwise dup(). + + + +

Return value:

+File Object of new descriptor + + + +
+ + + + +
errno ()
+
+ + Get the last system error code. + + + + + + + +

Return value:

+Error code + + + +
+ + + + +
exec (executable, ...)
+
+ + Execute a file to replace the current process. + + +

Parameters

+
    + +
  • + executable: Executable +
    • + +
  • + ...: Parameters +
    • + +
+ + + + +

Usage

+
    + +
  • The name of the executable is automatically passed as argv[0] + +
  • This function does not return on success. + +
+ + + + + +
+ + + + +
exece (executable, arguments, environment)
+
+ + Execute a file with a custom environment to replace the current process. + + +

Parameters

+
    + +
  • + executable: Executable +
    • + +
  • + arguments: Argument Table +
    • + +
  • + environment: Environment Table (optional) +
    • + +
+ + + + +

Usage

+
    + +
  • The name of the executable is automatically passed as argv[0] + +
  • This function does not return on success. + +
+ + + + + +
+ + + + +
execp (executable, ...)
+
+ + Invoke the shell and execute a file to replace the current process. + + +

Parameters

+
    + +
  • + executable: Executable +
    • + +
  • + ...: Parameters +
    • + +
+ + + + +

Usage

+
    + +
  • The name of the executable is automatically passed as argv[0] + +
  • This function does not return on success. + +
+ + + + + +
+ + + + +
fork ()
+
+ + (POSIX) Clone the current process. + + + + + + + +

Return value:

+the child process id for the parent process, 0 for the child process + + + +
+ + + + +
getaddrinfo (host, family, service)
+
+ + Look up a hostname and service via DNS. + + +

Parameters

+
    + +
  • + host: hostname to lookup (optional) +
    • + +
  • + family: address family ["any", "inet", "inet6"] +
    • + +
  • + service: service name or port (optional) +
    • + +
+ + + + + + +

Return value:

+Table containing one or more tables containing:
    +
  • family = ["inet", "inet6"]
    • +
  • socktype = ["stream", "dgram", "raw"]
    • +
  • address = Resolved IP-Address
    • +
  • port = Resolved Port (if service was given)
    • +
+ + + +
+ + + + +
getcwd ()
+
+ + Get the current working directory. + + + + + + + +

Return value:

+workign directory + + + +
+ + + + +
getenv (variable)
+
+ + Get the current environment table or a specific environment variable. + + +

Parameters

+
    + +
  • + variable: Variable (optional) +
    • + +
+ + + + + + +

Return value:

+environment table or single environment variable + + + +
+ + + + +
getgid ()
+
+ + (POSIX) Get the group id of the current process. + + + + + + + +

Return value:

+process group id + + + +
+ + + + +
getgr (group)
+
+ + (POSIX) Get all or a specific user group. + + +

Parameters

+
    + +
  • + group: Group ID or groupname (optional) +
    • + +
+ + + + + + +

Return value:

+Table containing:
    +
  • name = Group Name
    • +
  • gid = Group ID
    • +
  • passwd = Password
    • +
  • mem = {Member #1, Member #2, ...}
    • +
+ + + +
+ + + + +
getifaddrs ()
+
+ + (Linux, BSD) Get a list of available network interfaces and their addresses. + + + + + + + +

Return value:

+Table containing one or more tables containing:
    +
  • name = Interface Name
    • +
  • family = ["inet", "inet6", "packet"]
    • +
  • addr = Interface Address (IPv4, IPv6, MAC, ...)
    • +
  • broadaddr = Broadcast Address
    • +
  • dstaddr = Destination Address (Point-to-Point)
    • +
  • netmask = Netmask (if available)
    • +
  • prefix = Prefix (if available)
    • +
  • flags = Table of interface flags (up, multicast, loopback, ...)
    • +
  • data = Statistics (Linux, "packet"-family)
    • +
  • hatype = Hardware Type Identifier (Linix, "packet"-family)
    • +
  • ifindex = Interface Index (Linux, "packet"-family)
    • +
+ + + +
+ + + + +
getnameinfo (ipaddr)
+
+ + Reverse look up an IP-Address via DNS. + + +

Parameters

+
    + +
  • + ipaddr: IPv4 or IPv6-Address +
    • + +
+ + + + + + +

Return value:

+FQDN + + + +
+ + + + +
getpid ()
+
+ + Get the ID of the current process. + + + + + + + +

Return value:

+process id + + + +
+ + + + +
getppid ()
+
+ + (POSIX) Get the parent process id of the current process. + + + + + + + +

Return value:

+parent process id + + + +
+ + + + +
getproto (proto)
+
+ + Get all or a specifc proto entry. + + +

Parameters

+
    + +
  • + proto: protocol number or name to lookup (optional) +
    • + +
+ + + + + + +

Return value:

+Table (or if no parameter is given, a table of tables) + containing the following fields:
    +
  • name = Protocol Name
    • +
  • proto = Protocol Number
    • +
  • aliases = Table of alias names
    • +
+ + + +
+ + + + +
getprotobyname (name)
+
+ + Get protocol entry by name. + + +

Parameters

+
    + +
  • + name: protocol name to lookup +
    • + +
+ + + + +

Usage:

+This function returns nil if the given protocol is unknown. + + + +

Return value:

+Table containing the following fields:
    +
  • name = Protocol Name
    • +
  • proto = Protocol Number
    • +
  • aliases = Table of alias names
    • +
+ + + +
+ + + + +
getprotobynumber (proto)
+
+ + Get protocol entry by number. + + +

Parameters

+
    + +
  • + proto: protocol number to lookup +
    • + +
+ + + + +

Usage:

+This function returns nil if the given protocol is unknown. + + + +

Return value:

+Table containing the following fields:
    +
  • name = Protocol Name
    • +
  • proto = Protocol Number
    • +
  • aliases = Table of alias names
    • +
+ + + +
+ + + + +
getpw (user)
+
+ + (POSIX) Get all or a specific user account. + + +

Parameters

+
    + +
  • + user: User ID or username (optional) +
    • + +
+ + + + + + +

Return value:

+Table containing:
    +
  • name = Name
    • +
  • uid = ID
    • +
  • gid = Group ID
    • +
  • passwd = Password
    • +
  • dir = Home directory
    • +
  • gecos = Information
    • +
  • shell = Shell
    • +
+ + + +
+ + + + +
getsp (user)
+
+ + (Linux, Solaris) Get all or a specific shadow password entry. + + +

Parameters

+
    + +
  • + user: username (optional) +
    • + +
+ + + + + + +

Return value:

+Table containing:
    +
  • namp = Name
    • +
  • expire = Expiration Date
    • +
  • flag = Flags
    • +
  • inact = Inactivity Date
    • +
  • lstchg = Last change
    • +
  • max = Maximum
    • +
  • min = Minimum
    • +
  • warn = Warning
    • +
  • pwdp = Password Hash
    • +
+ + + +
+ + + + +
getuid ()
+
+ + (POSIX) Get the user id of the current process. + + + + + + + +

Return value:

+process user id + + + +
+ + + + +
kill (target, signal)
+
+ + (POSIX) Send a signal to one or more processes. + + +

Parameters

+
    + +
  • + target: Target process of process group. +
    • + +
  • + signal: Signal to send +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
nanosleep (seconds, nanoseconds)
+
+ + Sleep for a specified amount of time. + + +

Parameters

+
    + +
  • + seconds: Seconds to wait (optional) +
    • + +
  • + nanoseconds: Nanoseconds to wait (optional) +
    • + +
+ + + + +

Usage

+
    + +
  • Not all systems support nanosecond precision but you can expect + to have at least maillisecond precision. + +
  • This function is not signal-protected and may fail with EINTR. + +
+ + + +

Return value:

+true + + + +
+ + + + +
nice (nice)
+
+ + (POSIX) Change priority of current process. + + +

Parameters

+
    + +
  • + nice: Nice Value +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
open (path, flags, mode)
+
+ + Open a file. + + +

Parameters

+
    + +
  • + path: Filesystem path to open +
    • + +
  • + flags: Flag string or number (see open_flags). + ["r", "r+", "w", "w+", "a", "a+"] +
    • + +
  • + mode: File mode for newly created files (see chmod, umask). +
    • + +
+ + + + +

Usage:

+Although this function also supports the traditional fopen() + file flags it does not create a file stream but uses the open() syscall. + + + +

Return value:

+File Object + + + +

See also:

+ + +
+ + + + +
open_flags (flag1, ...)
+
+ + Generate flags for a call to open(). + + +

Parameters

+
    + +
  • + flag1: First Flag ["append", "creat", "excl", "nonblock", "ndelay", + "sync", "trunc", "rdonly", "wronly", "rdwr"] +
    • + +
  • + ...: More Flags [-"-] +
    • + +
+ + + + +

Usage

+
    + +
  • This function cannot fail and will never return nil. + +
  • The "nonblock" and "ndelay" flags are aliases. + +
  • The "nonblock", "ndelay" and "sync" flags are no-ops on Windows. + +
+ + + +

Return value:

+flag to be used as second paramter to open + + + +
+ + + + +
openlog (ident, flag1, ...)
+
+ + (POSIX) Open a connection to the system logger. + + +

Parameters

+
    + +
  • + ident: Identifier +
    • + +
  • + flag1: Flag 1 ["cons", "nowait", "pid", "perror", "ndelay", "odelay"] +
    • + +
  • + ...: More flags [-"-] +
    • + +
+ + + + + + + + +
+ + + + +
pipe ()
+
+ + Create a pipe. + + + + + + + +

Return values:

+
    + +
  1. File Object of the read end + +
  2. File Object of the write end + +
+ + + +
+ + + + +
poll (fds, timeout)
+
+ + 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. + + +

Parameters

+
    + +
  • + fds: Table containing one or more tables containing
      +
    • fd = I/O Descriptor [Socket Object, File Object (POSIX)]
      • +
    • events = events to wait for (bitfield generated with poll_flags)
      • +
    +
    • + +
  • + timeout: Timeout in milliseconds +
    • + +
+ + + + +

Usage

+
    + +
  • This function works in-place on the provided table and only + writes the revents field, you can use other fields on your demand. + +
  • All metamethods on the tables provided as fds are ignored. + +
  • 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. + +
  • If you want to wait on a TLS-Socket you have to use the underlying + socket instead. + +
  • On Windows poll is emulated through select(), can only be used + on socket descriptors and cannot take more than 64 descriptors per call. + +
  • This function is not signal-protected and may fail with EINTR. + +
+ + + +

Return values:

+
    + +
  1. number of ready IO descriptors + +
  2. the fds-table with revents-fields set + +
+ + + +

See also:

+ + +
+ + + + +
poll_flags (mode1, ...)
+
+ + Generate events-bitfield or parse revents-bitfield for poll. + + +

Parameters

+
    + +
  • + mode1: revents-Flag bitfield returned from poll to parse OR + ["in", "out", "err", "pri" (POSIX), "hup" (POSIX), "nval" (POSIX)] +
    • + +
  • + ...: More mode strings for generating the flag [-"-] +
    • + +
+ + + + + + +

Return value:

+table with boolean fields reflecting the mode parameter + OR bitfield to use for the events-Flag field + + + +

See also:

+ + +
+ + + + +
sendfile (socket, file, length)
+
+ + (POSIX) Send data from a file to a socket in kernel-space. + + +

Parameters

+
    + +
  • + socket: Socket Object +
    • + +
  • + file: File Object +
    • + +
  • + length: Amount of data to send (in Bytes). +
    • + +
+ + + + + + +

Return value:

+bytes sent + + + +
+ + + + +
setenv (variable, value)
+
+ + Set or unset a environment variable. + + +

Parameters

+
    + +
  • + variable: Variable +
    • + +
  • + value: Value (optional) +
    • + +
+ + + + +

Usage:

+The environment variable will be unset if value is ommited. + + + +

Return value:

+true + + + +
+ + + + +
setgid (gid)
+
+ + (POSIX) Set the group id of the current process. + + +

Parameters

+
    + +
  • + gid: New Group ID +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
setlogmask (priority)
+
+ + (POSIX) Set the logmask of the system logger for current process. + + +

Parameters

+
    + +
  • + priority: Priority ["emerg", "alert", "crit", "err", "warning", + "notice", "info", "debug"] +
    • + +
+ + + + + + + + +
+ + + + +
setsid ()
+
+ + (POSIX) Create a new session and set the process group ID. + + + + + + + +

Return value:

+session id + + + +
+ + + + +
setuid (gid)
+
+ + (POSIX) Set the user id of the current process. + + +

Parameters

+
    + +
  • + gid: New User ID +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
signal (signal, handler)
+
+ + Ignore or use set the default handler for a signal. + + +

Parameters

+
    + +
  • + signal: Signal +
    • + +
  • + handler: ["ign", "dfl"] +
    • + +
+ + + + + + +

Return value:

+true + + + +
+ + + + +
socket (domain, type)
+
+ + Create a new socket. + + +

Parameters

+
    + +
  • + domain: Domain ["inet", "inet6", "unix"] +
    • + +
  • + type: Type ["stream", "dgram", "raw"] +
    • + +
+ + + + + + +

Return value:

+Socket Object + + + +
+ + + + +
splice (fdin, fdout, length, flags)
+
+ + (Linux) Send data from / to a pipe in kernel-space. + + +

Parameters

+
    + +
  • + fdin: Input I/O descriptor +
    • + +
  • + fdout: Output I/O descriptor +
    • + +
  • + length: Amount of data to send (in Bytes). +
    • + +
  • + flags: (optional, bitfield generated by splice_flags) +
    • + +
+ + + + + + +

Return value:

+bytes sent + + + +

See also:

+ + +
+ + + + +
splice_flags (flag1, ...)
+
+ + (Linux) Generate a flag bitfield for a call to splice. + + +

Parameters

+
    + +
  • + flag1: First Flag ["move", "nonblock", "more"] +
    • + +
  • + ...: More flags [-"-] +
    • + +
+ + + + + + +

Return value:

+Flag bitfield + + + +

See also:

+ + +
+ + + + +
strerror (errno)
+
+ + Get the error message for the corresponding error code. + + +

Parameters

+
    + +
  • + errno: System error code +
    • + +
+ + + + + + +

Return value:

+Error message + + + +
+ + + + +
sysinfo ()
+
+ + (Linux) Get overall system statistics. + + + + + + + +

Return value:

+Table containing:
    +
  • uptime = system uptime in seconds
    • +
  • loads = {loadavg1, loadavg5, loadavg15}
    • +
  • totalram = total RAM
    • +
  • freeram = free RAM
    • +
  • sharedram = shared RAM
    • +
  • bufferram = buffered RAM
    • +
  • totalswap = total SWAP
    • +
  • freeswap = free SWAP
    • +
  • procs = number of running processes
    • +
+ + + +
+ + + + +
syslog (priority)
+
+ + (POSIX) Write a message to the system logger. + + +

Parameters

+
    + +
  • + priority: Priority ["emerg", "alert", "crit", "err", "warning", + "notice", "info", "debug"] +
    • + +
+ + + + + + + + +
+ + + + +
times ()
+
+ + (POSIX) Get process times. + + + + + + + +

Return value:

+Table containing:
    +
  • utime = user time
    • +
  • utime = system time
    • +
  • cutime = children user time
    • +
  • cstime = children system time
    • +
+ + + +
+ + + + +
tls (mode)
+
+ + Create a new TLS context. + + +

Parameters

+
    + +
  • + mode: TLS-Mode ["client", "server"] +
    • + +
+ + + + + + +

Return value:

+TLSContext Object + + + +
+ + + + +
umask (mask)
+
+ + Sets the file mode creation mask. + + +

Parameters

+
    + +
  • + mask: New creation mask (see chmod for format specifications) +
    • + +
+ + + + + + +

Return values:

+
    + +
  1. the old umask as decimal mode number + +
  2. the old umask as mode string + +
+ + + +
+ + + + +
uname ()
+
+ + (POSIX) Get information about current system and kernel. + + + + + + + +

Return value:

+Table containing:
    +
  • sysname = operating system
    • +
  • nodename = network name (usually hostname)
    • +
  • release = OS release
    • +
  • version = OS version
    • +
  • machine = hardware identifier
    • +
+ + + +
+ + + + +
waitpid (pid, flag1, ...)
+
+ + (POSIX) Wait for a process to change state. + + +

Parameters

+
    + +
  • + pid: Process ID (optional, default: any childprocess) +
    • + +
  • + flag1: Flag (optional) ["nohang", "untraced", "continued"] +
    • + +
  • + ...: More Flags [-"-] +
    • + +
+ + + + +

Usage:

+If the "nohang" is given this function becomes non-blocking. + + + +

Return values:

+
    + +
  1. process id of child or 0 if no child has changed state + +
  2. ["exited", "signaled", "stopped"] + +
  3. [exit code, terminate signal, stop signal] + +
+ + + +
+ + +
+ + + + + +
+ +
+ +
+

Valid XHTML 1.0!

+
+ +
+ + -- cgit v1.2.3