Module `nixio`

General POSIX IO library.

Functions

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

Tables

constants

Constants in the `nixio` module.

Functions

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)

Returns:

family = ["inet", "inet6"]
socktype = ["stream", "dgram", "raw"]
address = Resolved IP-Address
port = Resolved Port (if service was given)

getnameinfo (ipaddr)

Reverse look up an IP-Address via DNS.

Parameters:

ipaddr IPv4 or IPv6-Address

Returns:

FQDN

getifaddrs ()

(Linux, BSD) Get a list of available network interfaces and their addresses.

Returns:

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)

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

Returns:

Socket Object

Usage:

This functions calls getaddrinfo(), socket(),
 setsockopt() and bind() but NOT listen().

The <em>reuseaddr</em>-option is automatically set before binding.

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

Returns:

Socket Object

Usage:

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

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

Returns:

File Object

Usage:

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

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

Returns:

flag to be used as second paramter to open

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.

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)

Returns:

File Object of new descriptor

Usage:

This funcation calls dup2() if <em>newfd</em> is set, otherwise dup().

pipe ()

Create a pipe.

Returns:

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

errno ()

Get the last system error code.

Returns:

Error code

strerror (errno)

Get the error message for the corresponding error code.

Parameters:

errno System error code

Returns:

Error message

nanosleep (seconds, nanoseconds)

Sleep for a specified amount of time.

Parameters:

seconds Seconds to wait (optional)
nanoseconds Nanoseconds to wait (optional)

Returns:

true

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.

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

Returns:

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

Returns:

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

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.

fork ()

(POSIX) Clone the current process.

Returns:

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

kill (target, signal)

(POSIX) Send a signal to one or more processes.

Parameters:

target Target process of process group.
signal Signal to send

Returns:

true

getppid ()

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

Returns:

parent process id

getuid ()

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

Returns:

process user id

getgid ()

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

Returns:

process group id

setgid (gid)

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

Parameters:

gid New Group ID

Returns:

true

setuid (gid)

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

Parameters:

gid New User ID

Returns:

true

nice (nice)

(POSIX) Change priority of current process.

Parameters:

nice Nice Value

Returns:

true

setsid ()

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

Returns:

session id

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

Returns:

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

Usage:

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

gettime ()

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

Returns:

current time in seconds.

times ()

(POSIX) Get process times.

Returns:

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

uname ()

(POSIX) Get information about current system and kernel.

Returns:

sysname = operating system
nodename = network name (usually hostname)
release = OS release
version = OS version
machine = hardware identifier

chdir (path)

Change the working directory.

Parameters:

path New working directory

Returns:

true

signal (signal, handler)

Ignore or use set the default handler for a signal.

Parameters:

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

Returns:

true

getpid ()

Get the ID of the current process.

Returns:

process id

getcwd ()

Get the current working directory.

Returns:

workign directory

getenv (variable)

Get the current environment table or a specific environment variable.

Parameters:

variable Variable (optional)

Returns:

environment table or single environment variable

setenv (variable, value)

Set or unset a environment variable.

Parameters:

variable Variable
value Value (optional)

Returns:

true

Usage:

The environment variable will be unset if value is ommited.

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.

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.

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.

umask (mask)

Sets the file mode creation mask.

Parameters:

mask New creation mask (see chmod for format specifications)

Returns:

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

sysinfo ()

(Linux) Get overall system statistics.

Returns:

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

socket (domain, type)

Create a new socket.

Parameters:

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

Returns:

Socket Object

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

Returns:

bytes sent

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)

Returns:

bytes sent

Parameters:

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

Returns:

Flag bitfield

Parameters:

ident Identifier
flag1 Flag 1 ["cons", "nowait", "pid", "perror", "ndelay", "odelay"]
... More flags [-"-]

closelog ()

(POSIX) Close the connection to the system logger.

syslog (priority, message)

(POSIX) Write a message to the system logger.

Parameters:

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

setlogmask (priority)

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

Parameters:

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

crypt (key, salt)

(POSIX) Encrypt a user password.

Parameters:

key Key
salt Salt

Returns:

password hash

getgr (group)

(POSIX) Get all or a specific user group.

Parameters:

group Group ID or groupname (optional)

Returns:

name = Group Name
gid = Group ID
passwd = Password
mem = {Member #1, Member #2, ...}

getpw (user)

(POSIX) Get all or a specific user account.

Parameters:

user User ID or username (optional)

Returns:

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)

Returns:

namp = Name
expire = Expiration Date
flag = Flags
inact = Inactivity Date
lstchg = Last change
max = Maximum
min = Minimum
warn = Warning
pwdp = Password Hash

tls (mode)

Create a new TLS context.

Parameters:

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

Returns:

TLSContext Object

Tables

constants

Constants in the `nixio` module.

Fields:

stdin Standard input (FD 0)
stdout Standard output (FD 1)
stderr Standard error (FD 2)
version Nixio version as a string.

ldoc

Contents

Modules

Module nixio

Functions

Tables

Functions

Parameters:

Returns:

Parameters:

Returns:

Returns:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

See also:

Usage:

Parameters:

Returns:

Usage:

Parameters:

Returns:

Usage:

Returns:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Usage:

Returns:

Parameters:

Returns:

Returns:

Returns:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Returns:

Parameters:

Returns:

Usage:

Returns:

Returns:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Returns:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Usage:

Parameters:

Returns:

Module `nixio`