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 specific 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 specific 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 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 (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 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 (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!