Module luxio

Low-level bindings to POSIX functionality.

Luxio provides a very light-weight binding to many of the standard POSIX and common Unix library calls. Where possible, calls are very raw. In cases such as the dirent family, BSD sockets, the getaddrinfo family, and some other cases, they interfaces are somewhat “cooked” either to make them more efficient or even possible.

For the simple raw uncooked functions, all we present here is an example of the C prototype, and possible styles for use in Lua. You’ll have to go looking in man pages for actual information on their use.

Not all systems will provide all the functions described here.

Process creation and execution

fork() Fork a child process.
exec(path, ...) Execute a new program, replacing the current process.
execp(path, ...) Execute a new program, replacing the current process.

Process termination

waitpid(pid, options) Wait for a process to change state.
WIFEXITED(status) Check status macro for WIFEXITED.
WEXITSTATUS(status) Obtain exit status code from child.
WIFSIGNALLED(status) Check status macro for WIFSIGNALED.
WTERMSIG(status) Obtain signal used to kill child.
WCOREDUMP(status) Check for core dump.
WIFSTOPPED(status) Check whether process was stopped by delivery of a signal.
WSTOPSIG(status) Obtain signal number used to stop child.
WIFCONTINUED(status) Check status for WIFCONTINUED.
_exit([exit=0]) Terminate calling process.

Signals

kill(pid, signal) Send signal to a process or a group of processes.

Timer operations

alarm(seconds) Arranges for a SIGALRM signal to be delivered to the calling process in seconds seconds.
pause() Wait for a signal.
sleep(seconds) Sleep for the specified number of seconds.

Process identification

getpid() Get process identification.
getppid() Get process’s parent’s identification.

User identification

getuid() Get user identity.
geteuid() Get effective user identity.
getgid() Get group identity.
getegid() Get effective group identity.
setuid(uid) Set user identity.
setgid(gid) Set group identity.
getlogin() Get username.

System identification

uname-table uname() information table.
uname() Get name and information about current kernel.

Time

time() Get time in seconds.
times-table times() information table.
times() Get process times.

Environment variables

getenv(name) Get an environment variable.
setenv(name, value[, overwrite=0]) Set an environment variable.
unsetenv(name) Unsets an environment variable.

Directories

opendir(dir) Open a directory for enumeration.
fdopendir(fd) Open a directory for enumeration by open fd.
closedir(handle) Close a previously open directory.
dirent readdir() information table.
readdir(handle) Read a directory entry
rewinddir(handle) Reset directory stream

Working directory

chdir(path) Change working directory.
getcwd() Get the current working directory.

General file creation

open(path, flags[, mode]) Open and possibly create a file or device.
umask(mask) Set file mode creation mask.
link(existing, new) Make a new name for a file.
symlink(existing, new) Make a new (symbolic) name for a file.
readlink(path) Read value of symlink.
mkstemp(pattern) Create a unique temporary file.

Special file creation

mkdir(path, mode) Create a directory.
mkfifo(path, mode) Make a FIFO special file (a named pipe)

File removal

unlink(path) Delete a name and possibly the file it points to.
rmdir(path) Delete a directory.
rename(oldpath, newpath) Change the name or location of a file.

File characteristics

stat-table stat() information table Returned by stat and family.
stat(path) Get file status by path.
fstat(fd) Get file status by fd.
lstat(path) Get symlink status by path.
S_ISREG(mode) Check status macro S_ISREG for stat mode field.
S_ISDIR(mode) Check status macro S_ISDIR for stat mode field.
S_ISCHR(mode) Check status macro S_ISCHR for stat mode field.
S_ISBLK(mode) Check status macro S_ISBLK for stat mode field.
S_ISFIFO(mode) Check status macro S_ISFIFO for stat mode field.
S_ISLNK(mode) Check status macro S_ISLNK for stat mode field.
S_ISSOCK(mode) Check status macro S_ISSOCK for stat mode field.
chmod(path, mode) Change permissions of a file.
chmod(fd, mode) Change permissions of a file by fd.
chmod(path, owner, group) Change ownership of a file.
ftruncate(fd, lenght) Truncate a file to a specified length.

Pipes

pipe(pipe) Create pipe.
pipe2(pipe, flags) Create a pipe, with flags.
socketpair(domain, type, protocol, fdarray) Create a pair of connected sockets.

File descriptor manipulation

dup(oldfd) Duplicate a file descriptor.
dup2(oldfd, newfd) Duplicate a file descriptor to a specific one
dup3(oldfd, newfd, flags) Duplicate a file descriptor to a specific one, with flags.

File descriptor deassignment

close(fd) Close a file descriptor.

Input and output

read(fd, count) Read from a file descriptor.
write(fd, data[, start_offset=0]) Write to a file descriptor.
writev(fd, ...) Write data from multiple buffers.
sendfile(out_fd, in_fd[, offset=nil], count) Transfer data between descriptors.
splice(fd_in, off_in, fd_out, off_out, len, flags) Splice data to or from a pipe.

Control operations on files

fcntl(fd, command, ...) Manipulate file descriptor.
posix_fadvise(fd, offset, len, advice) Predeclare an access pattern for file data
lseek(fd, offset, whence) Reposition read/write file offset.

File synchronisation

fsync(fd) Synchronise a file’s in-core state with storage device.
fdatasync(fd) Synchronise only a file’s data and not unnessercery metadata.

General Terminal Interface

tcgetpgrp(fd) Get terminal forground process group.
tcsetpgrp(fd, pgrp_id) Set terminal forground process group.

Clock and timer functions

nanosleep(seconds, nanoseconds) High-resolution sleep.

Message passing

mq_open(name, oflag[, mode]) Open a message queue.
mq_close(mqdes) Close a message queue descriptor.
mq_unlink(name) Remove a message queue.
mq_send(queue, message, priority) Send a message to a message queue.
mq_receive(queue) Receive a message from a message queue.
mqattr-table Message queue attributes table.
mq_setattr(mqdes, flags) Set message queue attributes.
mq_getattr(mqdes) Get message queue attributes.
mq_timedsend(queue, message, priority, tv_sec, tv_nsec) Send a message to a queue, with a timeout.
mq_timedreceive(queue, tv_sec, tv_nsec) Receive a message from a message queue, with a timeout

Socket handling

socket(domain, type, protocol) Create an endpoint for communication.
listen(sockfd, backlog) Listen for connections on a socket.
shutdown(sockfd, how) Shut down part of a full-duplex connection.
connect(fd, sockaddr) Initiate a connection on a socket.
bind(fd, sockaddr) Bind a name to a socket.
accept(fd) Accept a connection on a socket.
getsockopt(fd, level, optname) Get options on a socket.
setsockopt(fd, level, optname, optvalue) Set an option on a socket.
gai_strerror(errno) Convert getaddrinfo-specific errors to strings.
addrinfo Result table from getaddrinfo.
getaddrinfo(node, service[, ai_flags=0[, ai_family=AF_UNSPEC[, ai_socktype=0[, ai_protocol=0]]]]) Network address and service translation.

Socket-related send and receive functions

send(fd, data[, flags=0]) Send a message on a socket.
sendto(fd, data[, flags=0], sockaddr) Send a message on a socket to a specific destination.
recv(fd, count[, flags=0]) Receive a message from a socket.
recvfrom(fd, count[, flags=0]) Receive a message from a socket, also returning sender information.

Time-related functions

zero_timeval() Create a new timeval, set to the epoch.
gettimeofday() Get the time of day.

Misc utility functions

strerror(errno) Return a string describing an error number.
openlog(ident, option, facility) Open a log file.
syslog(priority, log) Write a message to the open log.
closelog() Close the open log.
setlogmask(newmask, old) Set the log priority mask.
LOG_MASK(priority) Discover the bit used for a specific priority.

Character set conversion

icon_open(tocode, fromcode) Allocate descriptor for character set conversion.
iconv_close(handle) Close a previously-allocated iconv descriptor.
iconv(handle, buf) Perform character set conversion.


Process creation and execution

Functions to do with the creation of new processes and the execution of other programs.
fork()
Fork a child process. Return 0 in the child and the child’s process id in the parent.

Returns:

  1. number return value
  2. errno errno
exec(path, ...)
Execute a new program, replacing the current process. This function will not return when it succeeds, because the calling program is replaced by the new program. This function will only return if an error has occurred, the return value will be -1 and errno will be set to indicate the error.

This function is implemented with execv().

Parameters:

  • path string absolute path to executable
  • ... string parameters to pass to executatable

Returns:

  1. number return value
  2. errno errno
execp(path, ...)
Execute a new program, replacing the current process. This function will not return when it succeeds, because the calling program is replaced by the new program. This function will only return if an error has occurred, the return value will be -1 and errno will be set to indicate the error.

The difference between this function and exec, is that this function will search for the name of the executable in the colon-separated list of directories specified in the PATH environment variable.

This function is implemented with execp()

Parameters:

  • path string name of executable
  • ... string parameters to pass to executatable

Returns:

  1. number return value
  2. number errno

Process termination

Functions to do with the termination of processes.
waitpid(pid, options)

Wait for a process to change state.

This function obtains status information for one of the caller’s child processes. waitpid() will suspend execution of the calling thread until status information becomes available (unless luxio.WNOHANG is specified). If status information is available prior to the call to waitpid() then the function shall return immediately.

The pid argument specifies a set of child processes for which the status is requested. The waitpid() function shall only return the status of a child process from the following set:

  • If pid is -1, status is requested for any child process.
  • If pid is greater than 0, it specifies the process of a single process for which status is requested.
  • If pid is 0, status is requested for any child process whose process group ID is equal to that of the calling process.
  • If pid is less than -1, status is requested for any child process whose process group ID is equal to absolute value of pid.

The options argument is constructed from the bitwise OR of zero or more of the following flags:

  • luxio.WCONTINUED: report the status of any child process whose status has not been reported since it continued from a job control stop
  • luxio.WNOHANG: return immediately, do not wait for status to become available
  • luxio.WUNTRACED: return the status of any child process whose status has not been reported since it was stopped

Parameters:

  • pid number process id to wait on
  • options number options for call

Returns:

  1. number return value
  2. number or errno status code or errno if error
WIFEXITED(status)
Check status macro for WIFEXITED.

Returns true for status of a child process that terminated normally.

Parameters:

  • status number code from waitpid()

Returns:

    number true or false
WEXITSTATUS(status)
Obtain exit status code from child.

If the value of WIFEXITED(status) is true, return the exit code of the child process.

Parameters:

  • status number code from waitpid()

Returns:

    number exit status code
WIFSIGNALLED(status)
Check status macro for WIFSIGNALED.

Returns true for status of a child process that was terminated by an uncaught signal.

Parameters:

  • status number code from waitpid()

Returns:

    number true or false
WTERMSIG(status)
Obtain signal used to kill child.

If the value of WIFSIGNALED(status) is true, return the number of the signal that terminated the child process.

Parameters:

  • status number code from waitpid()

Returns:

    number signal number
WCOREDUMP(status)
Check for core dump.

Returns true if the child process produced a core dump. This should only be used if WIFSIGNALED(status) returns true.

WCOREDUMP is not specified in POSIX.1-2001 and is not available on some platforms, e.g. AIX and Solaris.

Parameters:

  • status number code from waitpid()

Returns:

    number true or false
WIFSTOPPED(status)
Check whether process was stopped by delivery of a signal.

Returns true if the child process was stopped by delivery of a signal. This can only return true if waitpid() was called with the luxio.WUNTRACED option.

Parameters:

  • status number code from waitpid()

Returns:

    number true or false
WSTOPSIG(status)
Obtain signal number used to stop child.

If the value of WIFSTOPPED(status) is true, return the number of the signal that caused the child to stop.

Parameters:

  • status number code from waitpid()

Returns:

    number signal number
WIFCONTINUED(status)
Check status for WIFCONTINUED.

Returns true if child process was resumed by SIGCONT.

(since Linux 2.6.10).

Parameters:

  • status number code from waitpid()

Returns:

    number true or false
_exit([exit=0])
Terminate calling process. Does not return.

Terminates calling process “immediately”, this differs from exit(3) in that any functions registered via atexit(3) or on_exit(3) are not called when the process exits.

Any open file descriptors are closed, any children of the process are inherited by pid 1 (init), and the process’s parent is sent a SIGCHLD signal.

Parameters:

  • exit number status code. (default 0)

Signals

Functions related to sending signals.

All signals are defined symbolically: luxio.SIGKILL, luxio.SIGINT etc, for a complete list of signals consult signal(2) or signal(7) man pages.

kill(pid, signal)
Send signal to a process or a group of processes.

This function sends a signal to a process or a group of processes based on the value of the pid parameter. The signal sent is specified by the signal parameter.

If pid is positive, then signal is sent to the process with the ID specified by pid.

If pid equals 0, then signal is sent to all processes whose process group ID is equal to the process group ID of the caller, and for which the caller has permission to send a signal (excluding an unspecified set of system processes).

If pid equals -1, then signal is sent to every process for which the calling process has permission to send signals (excluding an unspecified set of system processes).

If pid is less than -1, then signal is sent to every process (excluding an unspecified set of system processes) whose process group ID is equal to the absolute value of pid.

If signal is 0 then no signal is sent, but error checking is still performed. This may be used to check for the existence of a process ID or process group ID.

Return 0 on success (at least one signal was sent). On error -1 is returned and errno will be set.

Parameters:

  • pid number signal destination
  • signal number signal to send

Returns:

  1. number return value
  2. errno errno

Timer operations

alarm(seconds)
Arranges for a SIGALRM signal to be delivered to the calling process in seconds seconds.

Parameters:

  • seconds number How long to wait before signal delivery

Returns:

    number return value
pause()
Wait for a signal.

pause() causes the caller to suspend execution until either a signal is caught or a signal is received which terminates the process.

pause() returns only when a signal is caught and the signal catching function returns. In which case pause() will return -1 and errno will be set to EINTR.

Returns:

    number return value
sleep(seconds)
Sleep for the specified number of seconds.

Parameters:

  • seconds number number of seconds to sleep

Returns:

    number return value

Process identification

getpid()
Get process identification.

Returns the process ID of the calling process.

Returns:

    number pid
getppid()
Get process’s parent’s identification.

Returns the process ID of the parent of calling process

Returns:

    number pid

User identification

getuid()
Get user identity.

Returns the real user ID of the calling process.

Returns:

    number uid
geteuid()
Get effective user identity.

Returns the effective user ID of the calling process.

Returns:

    number uid
getgid()
Get group identity.

Returns the real group ID of the calling process.

Returns:

    number gid
getegid()
Get effective group identity.

Returns the effective group ID of the calling process

Returns:

    number gid
setuid(uid)
Set user identity.

Set the effective user ID of the calling process. If the effective UID of the caller is root the real UID and saved set-user-ID are also set.

Returns zero on success. Returns -1 on failure, with errno set appropriately.

setuid() can fail even when the caller is UID 0, it is a grave security error to fail to check return value of setuid().

Parameters:

  • uid number

Returns:

  1. number return value
  2. errno errno
setgid(gid)
Set group identity.

Set the effective group ID of the calling process. If the caller is the superuser, the real GID and saved set-group-ID are also set.

Returns zero on success. Returns -1 on failure, with errno set appropriately.

Parameters:

  • gid number

Returns:

  1. number return value
  2. errno errno
getlogin()
Get username.

Returns 0 on success and non-zero on failure.

On success the second return value contains the name of the user logged in on the process’s controlling terminal. On failure the second return value contains errno.

Returns:

  1. number return value
  2. string or errno username or errno

System identification

uname-table
uname() information table. Returned by uname. Some fields are OS-specific.

Fields:

  • sysname Operating system name, such as Linux or NetBSD.
  • nodename System’s name
  • release Operating systems’s release version
  • machine Hardware identifier
  • domainname NIS or YP domain name Note: GNU extension
uname()
Get name and information about current kernel.

Returns:

  1. number return value
  2. uname-table or errno result table, or errno.

Time

time()
Get time in seconds.

On success, returns the time as the number of seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). On failure, returns -1 with errno set appropriately.

Returns:

  1. number seconds since epoch.
  2. number errno
times-table
times() information table. Returned by times.

Fields:

  • utime user time
  • stime system time
  • cutime user time of children
  • cstime system time of children
times()
Get process times.

Returns:

  1. number return value
  2. times-table or errno Time data, or errno.

Environment variables

getenv(name)
Get an environment variable.

Returns the value of the environment variable, or nil if the environment variable does not exist.

Parameters:

Returns:

    string or nil return value
setenv(name, value[, overwrite=0])
Set an environment variable.

Returns zero on success, or -1 on error, with errno set appropriately.

Add the variable with name name to the environment if it doesn’t already exist. If it does already exist then overwrite it if overwrite is non-zero, otherwise do nothing. Note: setenv() still returns successfully if the variable is found and overwrite is zero.

Parameters:

Returns:

  1. number return value
  2. errno
unsetenv(name)
Unsets an environment variable.

Returns zero on success, or -1 on error, with errno set appropriately.

Parameters:

Returns:

  1. number return value
  2. errno

Directories

opendir(dir)
Open a directory for enumeration.

Parameters:

  • dir string directory to enumerate

Returns:

  1. DIR or nil DIR object, or nil on error
  2. errno errno
fdopendir(fd)
Open a directory for enumeration by open fd.

Parameters:

  • fd number file descriptor

Returns:

  1. DIR or nil DIR object, or nil on error
  2. errno errno
closedir(handle)
Close a previously open directory.

Parameters:

  • handle DIR DIR object to close
dirent
readdir() information table. Returned by readdir. Some fields are OS-specific.

Fields:

  • d_ino inode number
  • d_name file name
  • d_type file type Note: d_type is not supported by all filesystems.
readdir(handle)
Read a directory entry

Parameters:

  • handle DIR directory handle

Returns:

  1. dirent or nil directory entry table, or nil on error
  2. errno errno
rewinddir(handle)
Reset directory stream

Parameters:

  • handle DIR

Working directory

chdir(path)
Change working directory.

Returns zero on success, or -1 on error with errno set appropriately.

Parameters:

Returns:

  1. number return value
  2. errno errno
getcwd()
Get the current working directory.

Returns:

  1. string or nil path or nil on error
  2. errno

General file creation

open(path, flags[, mode])
Open and possibly create a file or device.

Returns file descriptor on success. On error returns -1 with errno set appropriately.

mode is an optional parameter that may be a bitwise OR of the following constants:

  • Read, write and executable

    • luxio.S_IRWXU - User read, write and executable
    • luxio.S_IRWXG - Group read, write and executable
    • luxio.S_IRWXO - World read, write and executable
  • Readable

    • luxio.S_IRUSR - User readable
    • luxio.S_IRGRP - Group readable
    • luxio.S_IROTH - World readable
  • Writeable

    • luxio.S_IWUSR - User writeable
    • luxio.S_IWGRP - Group writeable
    • luxio.S_IWOTH - World writeable
  • Executable

    • luxio.S_IXUSR - User executable
    • luxio.S_IXGRP - Group executable
    • luxio.S_IXOTH - World executable

flags is a parameter that may be a bitwise OR of the following constants:

  • luxio.O_RDONLY
  • luxio.O_WRONLY
  • luxio.O_RDWR
  • luxio.O_APPEND
  • luxio.O_ASYNC
  • luxio.O_CLOEXEC
  • luxio.O_CREAT
  • luxio.O_EXCL
  • luxio.O_NOCTTY
  • luxio.O_NONBLOCK
  • luxio.O_SYNC
  • luxio.O_TRUNC
  • luxio.O_DIRECT
  • luxio.O_NOFOLLOW
  • luxio.O_NOATIME
  • luxio.O_LARGEFILE

Note: Not all of these constants are available on all platforms. Consult the open(2) man pages for details.

Parameters:

  • path string
  • flags number
  • mode number , must be specified if creating. (optional)

Returns:

  1. result File descriptor
  2. errno
umask(mask)
Set file mode creation mask.

Parameters:

  • mask number
link(existing, new)
Make a new name for a file.

Parameters:

  • existing string existing file name
  • new string new file name

Returns:

  1. number return value
  2. errno
symlink(existing, new)
Make a new (symbolic) name for a file.

Parameters:

  • existing string existing file name
  • new string new file name

Returns:

  1. number return value
  2. errno
readlink(path)
Read value of symlink.

Parameters:

Returns:

  1. number return value
  2. string or errno value, or errno on error
mkstemp(pattern)
Create a unique temporary file.

Parameters:

  • pattern string or nil Pattern to use, or nil for default pattern.

Returns:

  1. number FD of temporary file (-1 on error)
  2. string or errno Filename of temporary file or errno on error

Special file creation

mkdir(path, mode)
Create a directory.

Parameters:

Returns:

  1. number return value
  2. errno
mkfifo(path, mode)
Make a FIFO special file (a named pipe)

Parameters:

Returns:

  1. number return value
  2. errno

File removal

unlink(path)
Delete a name and possibly the file it points to.

Parameters:

Returns:

  1. number return value
  2. errno
rmdir(path)
Delete a directory.

Parameters:

Returns:

  1. number return value
  2. errno
rename(oldpath, newpath)
Change the name or location of a file.

Parameters:

Returns:

  1. number return value
  2. errno

File characteristics

stat-table
stat() information table Returned by stat and family.

Fields:

  • dev id of device containing file
  • ino inode of file
  • mode protection mode
  • nlink number of links
  • uid user id of owner
  • gid group id of owner
  • rdev device id (if special file)
  • size total size, in bytes
  • blksize blocksize for file system I/O
  • blocks number of blocks allocated
  • atime time of last access
  • mtime time of last modification
  • ctime time of last status change
stat(path)
Get file status by path.

Parameters:

Returns:

  1. number return value
  2. errno or stat-table
fstat(fd)
Get file status by fd.

Parameters:

  • fd number

Returns:

  1. number return value
  2. errno or stat-table
lstat(path)
Get symlink status by path.

Parameters:

Returns:

  1. number return value
  2. errno or stat-table
S_ISREG(mode)
Check status macro S_ISREG for stat mode field.

Parameters:

  • mode number field from a stat call

Returns:

    number
S_ISDIR(mode)
Check status macro S_ISDIR for stat mode field.

Parameters:

  • mode number field from a stat call

Returns:

    number
S_ISCHR(mode)
Check status macro S_ISCHR for stat mode field.

Parameters:

  • mode number field from a stat call

Returns:

    number
S_ISBLK(mode)
Check status macro S_ISBLK for stat mode field.

Parameters:

  • mode number field from a stat call

Returns:

    number
S_ISFIFO(mode)
Check status macro S_ISFIFO for stat mode field.

Parameters:

  • mode number field from a stat call

Returns:

    number
S_ISLNK(mode)
Check status macro S_ISLNK for stat mode field. Not always available.

Parameters:

  • mode number field from a stat call

Returns:

    number
S_ISSOCK(mode)
Check status macro S_ISSOCK for stat mode field. Not always available.

Parameters:

  • mode number field from a stat call

Returns:

    number
chmod(path, mode)
Change permissions of a file.

Parameters:

Returns:

  1. number return value
  2. errno
chmod(fd, mode)
Change permissions of a file by fd.

Parameters:

  • fd number
  • mode number

Returns:

  1. number return value
  2. errno
chmod(path, owner, group)
Change ownership of a file.

Parameters:

  • path string
  • owner number
  • group number

Returns:

  1. number return value
  2. errno
ftruncate(fd, lenght)
Truncate a file to a specified length.

Parameters:

  • fd number
  • lenght number

Returns:

  1. number return value
  2. errno

Pipes

pipe(pipe)
Create pipe.

Parameters:

  • pipe table A table for which this function will fill in the keys 1 and 2

Returns:

  1. number return value
  2. errno
pipe2(pipe, flags)
Create a pipe, with flags. Not available on all systems.

Parameters:

  • pipe table A table for which this function will fill in the keys 1 and 2
  • flags number

Returns:

  1. number return value
  2. errno
socketpair(domain, type, protocol, fdarray)
Create a pair of connected sockets.

Parameters:

  • domain number
  • type number
  • protocol number
  • fdarray table The values [1] and [2] are filled in with descriptors

Returns:

  1. number return value
  2. errno

File descriptor manipulation

dup(oldfd)
Duplicate a file descriptor.

Parameters:

  • oldfd number

Returns:

  1. number return value
  2. errno
dup2(oldfd, newfd)
Duplicate a file descriptor to a specific one

Parameters:

  • oldfd number
  • newfd number

Returns:

  1. number return value
  2. errno
dup3(oldfd, newfd, flags)
Duplicate a file descriptor to a specific one, with flags. Not available on all platforms.

Parameters:

  • oldfd number
  • newfd number
  • flags number

Returns:

  1. number return value
  2. errno

File descriptor deassignment

close(fd)
Close a file descriptor.

Parameters:

  • fd number

Returns:

  1. number return value
  2. errno

Input and output

read(fd, count)
Read from a file descriptor.

Parameters:

  • fd number
  • count number

Returns:

  1. number or string return value or read data
  2. errno
write(fd, data[, start_offset=0])
Write to a file descriptor.

Parameters:

  • fd number
  • data string
  • start_offset number (default 0)

Returns:

  1. number return value
  2. errno
writev(fd, ...)
Write data from multiple buffers.

Parameters:

Returns:

  1. number return value
  2. errno
sendfile(out_fd, in_fd[, offset=nil], count)
Transfer data between descriptors. Not available on all systems.

Parameters:

  • out_fd number
  • in_fd number
  • offset number (default nil)
  • count number

Returns:

  1. number return value
  2. errno
splice(fd_in, off_in, fd_out, off_out, len, flags)
Splice data to or from a pipe. Not available on all systems.

Parameters:

  • fd_in number
  • off_in number
  • fd_out number
  • off_out number
  • len number
  • flags number

Returns:

  1. number return value
  2. errno

Control operations on files

fcntl(fd, command, ...)
Manipulate file descriptor. Supported commands: F_GETFD/F_SETFD, F_GETFL/F_SETFL, F_GETPIPE_SZ/F_SETPIPE_SZ, F_DUPFD, F_DUPFD_CLOEXEC, F_SETLK, F_SETLKW, F_GETLK.

Commands that take a struct, such as F_SETLK, accept a table as the argument, with keys named as the struct’s.

Parameters:

  • fd number
  • command number
  • ... ...

Returns:

  1. number return value
  2. errno
posix_fadvise(fd, offset, len, advice)
Predeclare an access pattern for file data

Parameters:

  • fd number
  • offset number
  • len number
  • advice number

Returns:

    errno
lseek(fd, offset, whence)
Reposition read/write file offset.

Parameters:

  • fd number
  • offset number
  • whence number

Returns:

  1. number return value
  2. errno

File synchronisation

fsync(fd)
Synchronise a file’s in-core state with storage device.

Parameters:

  • fd number

Returns:

  1. number return value
  2. errno
fdatasync(fd)
Synchronise only a file’s data and not unnessercery metadata. Not available on all systems.

Parameters:

  • fd number

Returns:

  1. number return value
  2. errno

General Terminal Interface

tcgetpgrp(fd)
Get terminal forground process group.

Parameters:

  • fd number

Returns:

  1. number return value
  2. errno
tcsetpgrp(fd, pgrp_id)
Set terminal forground process group.

Parameters:

  • fd number
  • pgrp_id number

Returns:

  1. number return value
  2. errno

Clock and timer functions

nanosleep(seconds, nanoseconds)
High-resolution sleep.

Parameters:

  • seconds number
  • nanoseconds number

Returns:

  1. number return value
  2. errno
  3. number remaining seconds
  4. number remaining nanosections

Message passing

POSIX message passing is not available on all platforms.
mq_open(name, oflag[, mode])
Open a message queue.

Parameters:

  • name string
  • oflag number
  • mode number (optional)

Returns:

  1. mq or number message queue, or return value
  2. errno
mq_close(mqdes)
Close a message queue descriptor.

Parameters:

  • mqdes mq

Returns:

  1. number return value
  2. errno
mq_unlink(name)
Remove a message queue.

Parameters:

Returns:

  1. number return value
  2. errno
mq_send(queue, message, priority)
Send a message to a message queue.

Parameters:

  • queue mq
  • message string
  • priority number

Returns:

  1. number return value
  2. errno
mq_receive(queue)
Receive a message from a message queue.

Parameters:

  • queue mq

Returns:

  1. number return value
  2. errno
  3. string or nil message data, or nil in case of error
  4. number or nil message priority, or nil in case of error
mqattr-table
Message queue attributes table.

Fields:

  • mq_flags 0 or O_NONBLOCK
  • mq_maxmsg Maximum number of messages on queue
  • mq_msgsize Maximum size of message (in bytes)
  • mq_curmsgs Number of messages currently on queue
mq_setattr(mqdes, flags)
Set message queue attributes. As only the flags can be changed, this does not take a table.

Parameters:

  • mqdes mq
  • flags number

Returns:

  1. number return value
  2. errno
  3. mqattr-table new attribute table
mq_getattr(mqdes)
Get message queue attributes.

Parameters:

  • mqdes mq

Returns:

  1. number return value
  2. errno
  3. mqattr-table current queue attributes
mq_timedsend(queue, message, priority, tv_sec, tv_nsec)
Send a message to a queue, with a timeout. Not available on some systems.

Parameters:

  • queue mq
  • message string
  • priority number
  • tv_sec number
  • tv_nsec number

Returns:

  1. number return value
  2. errno
mq_timedreceive(queue, tv_sec, tv_nsec)
Receive a message from a message queue, with a timeout

Parameters:

  • queue mq
  • tv_sec number
  • tv_nsec number

Returns:

  1. number return value
  2. errno
  3. string or nil message data, or nil in case of error
  4. number or nil message priority, or nil in case of error

Socket handling

This interface is slightly cooked. We provide userdata encapsulations for sockaddr and addrinfo types. Use getaddrinfo() to obtain an addrinfo object, then use ipairs() over it to get each entry to try.

r, addrinfo = getaddrinfo(“www.rjek.com”, “80”, 0, l.AF_UNSPEC, l.SOCK_STREAM) for _, ai in ipairs(addrinfo) do sock = socket(ai.ai_family, ai.ai_socktype, ai.ai_protocol) if connect(sock, ai.ai_addr) >= 0 then break end end

socket(domain, type, protocol)
Create an endpoint for communication.

Parameters:

  • domain number
  • type number
  • protocol number

Returns:

  1. number return value
  2. errno
listen(sockfd, backlog)
Listen for connections on a socket.

Parameters:

  • sockfd number
  • backlog number

Returns:

  1. number return value
  2. errno
shutdown(sockfd, how)
Shut down part of a full-duplex connection.

Parameters:

  • sockfd number
  • how number

Returns:

  1. number return value
  2. errno
connect(fd, sockaddr)
Initiate a connection on a socket.

Parameters:

  • fd number
  • sockaddr sockaddr

Returns:

  1. number return value
  2. errno
bind(fd, sockaddr)
Bind a name to a socket.

Parameters:

  • fd number
  • sockaddr sockaddr

Returns:

  1. number return value
  2. errno
accept(fd)
Accept a connection on a socket.

Parameters:

  • fd number

Returns:

  1. number return value
  2. errno or sockaddr
getsockopt(fd, level, optname)
Get options on a socket.

Parameters:

  • fd number
  • level number
  • optname number

Returns:

  1. number return value
  2. errno, number or string
setsockopt(fd, level, optname, optvalue)
Set an option on a socket.

Parameters:

  • fd number
  • level number
  • optname number
  • optvalue

Returns:

  1. number return value
  2. errno
gai_strerror(errno)
Convert getaddrinfo-specific errors to strings.

Parameters:

  • errno errno

Returns:

    string error string
addrinfo
Result table from getaddrinfo.

Fields:

  • ai_flags number
  • ai_family number
  • ai_socktype number
  • ai_protocol number
  • ai_canonname string
  • ai_addr sockaddr type containing address information.
getaddrinfo(node, service[, ai_flags=0[, ai_family=AF_UNSPEC[, ai_socktype=0[, ai_protocol=0]]]])
Network address and service translation.

Parameters:

  • node string
  • service string
  • ai_flags number (default 0)
  • ai_family number (default AF_UNSPEC)
  • ai_socktype number (default 0)
  • ai_protocol number (default 0)

Returns:

    errno or table table of result addrinfo entries

Socket-related send and receive functions

send(fd, data[, flags=0])
Send a message on a socket.

Parameters:

  • fd number
  • data string
  • flags number (default 0)

Returns:

  1. number return value
  2. errno
sendto(fd, data[, flags=0], sockaddr)
Send a message on a socket to a specific destination.

Parameters:

  • fd number
  • data string
  • flags number (default 0)
  • sockaddr sockaddr

Returns:

  1. number return value
  2. errno
recv(fd, count[, flags=0])
Receive a message from a socket.

Parameters:

  • fd number
  • count number
  • flags number (default 0)

Returns:

  1. number or string return value if error, otherwise string
  2. errno
recvfrom(fd, count[, flags=0])
Receive a message from a socket, also returning sender information.

Parameters:

  • fd number
  • count number
  • flags number (default 0)

Returns:

  1. number or string return value if error, otherwise string
  2. errno
  3. sockaddr or nil

Time-related functions

The time-related functions in Luxio are medium-rare. A timeval type is exposed as a userdata type, complete with comparison, addition/subtraction, and tostring metamethods. You can set the fields tv_sec, tv_usec, seconds, and useconds.
zero_timeval()
Create a new timeval, set to the epoch.

Returns:

    timeval
gettimeofday()
Get the time of day.

Returns:

  1. timeval or number return value
  2. errno

Misc utility functions

strerror(errno)
Return a string describing an error number.

Parameters:

  • errno errno

Returns:

    string
openlog(ident, option, facility)
Open a log file.

Parameters:

  • ident string
  • option number
  • facility number
syslog(priority, log)
Write a message to the open log.

Parameters:

  • priority number
  • log string message
closelog()
Close the open log.
setlogmask(newmask, old)
Set the log priority mask.

Parameters:

  • newmask number
  • old number mask
LOG_MASK(priority)
Discover the bit used for a specific priority.

Parameters:

  • priority number

Returns:

    number mask

Character set conversion

icon_open(tocode, fromcode)
Allocate descriptor for character set conversion.

Parameters:

Returns:

  1. iconv or number return value
  2. errno
iconv_close(handle)
Close a previously-allocated iconv descriptor.

Parameters:

Returns:

  1. number return vlaue
  2. errno
iconv(handle, buf)
Perform character set conversion.

Parameters:

Returns:

  1. string or number resulting string or return value in case of error
  2. errno
  3. string or nil partial result when error.
generated by LDoc 1.4.6 Last updated 2018-03-18 13:49:12