# 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:

  - umask
  - open_flags
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 parameter 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 occurred.

  ### 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
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:

  - poll
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 omitted.

  ### 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
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:

  - splice
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]