Module `nixio`

General POSIX IO library.

Functions

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

Functions

nixio.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

nixio.chdir (path)

Change the working directory.

Parameters

path: New working directory

Return value:

true

nixio.closelog ()

(POSIX) Close the connection to the system logger.

nixio.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

nixio.crypt (key, salt)

(POSIX) Encrypt a user password.

Parameters

key: Key
salt: Salt

Return value:

password hash

nixio.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

nixio.errno ()

Get the last system error code.

Return value:

Error code

nixio.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.

nixio.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.

nixio.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.

nixio.fork ()

(POSIX) Clone the current process.

Return value:

the child process id for the parent process, 0 for the child process

nixio.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)

nixio.getcwd ()

Get the current working directory.

Return value:

workign directory

nixio.getenv (variable)

Get the current environment table or a specific environment variable.

Parameters

variable: Variable (optional)

Return value:

environment table or single environment variable

nixio.getgid ()

(POSIX) Get the group id of the current process.

Return value:

process group id

nixio.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, ...}

nixio.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)

nixio.getnameinfo (ipaddr)

Reverse look up an IP-Address via DNS.

Parameters

ipaddr: IPv4 or IPv6-Address

Return value:

FQDN

nixio.getpid ()

Get the ID of the current process.

Return value:

process id

nixio.getppid ()

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

Return value:

parent process id

nixio.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

nixio.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

nixio.gettime ()

Get current time in seconds (since epoch: January 1, 1970 UTC).

Return value:

current time in seconds.

nixio.getuid ()

(POSIX) Get the user id of the current process.

Return value:

process user id

nixio.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

nixio.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

nixio.nice (nice)

(POSIX) Change priority of current process.

Parameters

nice: Nice Value

Return value:

true

nixio.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

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

nixio.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 [-"-]

nixio.pipe ()

Create a pipe.

Return values:

File Object of the read end
File Object of the write end

nixio.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:

number of ready IO descriptors
the fds-table with revents-fields set

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

Parameters

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

Return value:

bytes sent

nixio.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

nixio.setgid (gid)

(POSIX) Set the group id of the current process.

Parameters

gid: New Group ID

Return value:

true

nixio.setlogmask (priority)

(POSIX) Set the logmask of the system logger for current process.

Parameters

priority: Priority ["emerg", "alert", "crit", "err", "warning", "notice", "info", "debug"]

nixio.setsid ()

(POSIX) Create a new session and set the process group ID.

Return value:

session id

nixio.setuid (gid)

(POSIX) Set the user id of the current process.

Parameters

gid: New User ID

Return value:

true

nixio.signal (signal, handler)

Ignore or use set the default handler for a signal.

Parameters

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

Return value:

true

nixio.socket (domain, type)

Create a new socket.

Parameters

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

Return value:

Socket Object

nixio.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

Parameters

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

Return value:

Flag bitfield

Parameters

errno: System error code

Return value:

Error message

nixio.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

nixio.syslog (priority)

(POSIX) Write a message to the system logger.

Parameters

priority: Priority ["emerg", "alert", "crit", "err", "warning", "notice", "info", "debug"]

nixio.times ()

(POSIX) Get process times.

Return value:

Table containing:

utime = user time
utime = system time
cutime = children user time
cstime = children system time

nixio.tls (mode)

Create a new TLS context.

Parameters

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

Return value:

TLSContext Object

nixio.umask (mask)

Sets the file mode creation mask.

Parameters

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

Return values:

the old umask as decimal mode number
the old umask as mode string

nixio.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

nixio.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:

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

LuaDoc

Modules

Module nixio

Functions

Functions

Parameters

Usage

Return value:

Parameters

Return value:

Parameters

Usage:

Return value:

Parameters

Return value:

Parameters

Usage:

Return value:

Return value:

Parameters

Usage

Parameters

Usage

Parameters

Usage

Return value:

Parameters

Return value:

Return value:

Parameters

Return value:

Return value:

Parameters

Return value:

Return value:

Parameters

Return value:

Return value:

Return value:

Parameters

Return value:

Parameters

Return value:

Return value:

Return value:

Parameters

Return value:

Parameters

Usage

Return value:

Parameters

Return value:

Parameters

Usage:

Return value:

See also:

Parameters

Usage

Return value:

Parameters

Return values:

Parameters

Usage

Return values:

See also:

Parameters

Return value:

See also:

Parameters

Return value:

Parameters

Usage:

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Return value:

Parameters

Module `nixio`