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:
- number return value
- 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:
Returns:
- number return value
- 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:
Returns:
- number return value
- 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 (unlessluxio.WNOHANG
is specified). If status information is available prior to the call towaitpid()
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 ofpid
.
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 stopluxio.WNOHANG
: return immediately, do not wait for status to become availableluxio.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:
- number return value
- number or errno status code or errno if error
- If
- 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 theluxio.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 viaatexit(3)
oron_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 thesignal
parameter.If
pid
is positive, thensignal
is sent to the process with the ID specified bypid
.If
pid
equals 0, thensignal
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, thensignal
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, thensignal
is sent to every process (excluding an unspecified set of system processes) whose process group ID is equal to the absolute value ofpid
.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:
- number return value
- 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 casepause()
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 ofsetuid().
Parameters:
- uid number
Returns:
- number return value
- 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:
- number return value
- 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:
- number return value
- 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:
- number return value
- 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:
- number seconds since epoch.
- 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:
- number return value
- 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:
- name string
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 ifoverwrite
is non-zero, otherwise do nothing. Note:setenv()
still returns successfully if the variable is found andoverwrite
is zero.Parameters:
Returns:
- number return value
- errno
- unsetenv(name)
-
Unsets an environment variable.
Returns zero on success, or -1 on error, with errno set appropriately.
Parameters:
- name string
Returns:
- number return value
- errno
Directories
- opendir(dir)
-
Open a directory for enumeration.
Parameters:
- dir string directory to enumerate
Returns:
- DIR or nil DIR object, or nil on error
- errno errno
- fdopendir(fd)
-
Open a directory for enumeration by open fd.
Parameters:
- fd number file descriptor
Returns:
- DIR or nil DIR object, or nil on error
- 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:
- dirent or nil directory entry table, or nil on error
- 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:
- path string
Returns:
- number return value
- errno errno
- getcwd()
-
Get the current working directory.
Returns:
- string or nil path or nil on error
- 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 executableluxio.S_IRWXG
- Group read, write and executableluxio.S_IRWXO
- World read, write and executable
Readable
luxio.S_IRUSR
- User readableluxio.S_IRGRP
- Group readableluxio.S_IROTH
- World readable
Writeable
luxio.S_IWUSR
- User writeableluxio.S_IWGRP
- Group writeableluxio.S_IWOTH
- World writeable
Executable
luxio.S_IXUSR
- User executableluxio.S_IXGRP
- Group executableluxio.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:
- result File descriptor
- errno
- umask(mask)
-
Set file mode creation mask.
Parameters:
- mask number
- link(existing, new)
-
Make a new name for a file.
Parameters:
Returns:
- number return value
- errno
- symlink(existing, new)
-
Make a new (symbolic) name for a file.
Parameters:
Returns:
- number return value
- errno
- readlink(path)
-
Read value of symlink.
Parameters:
- path string
Returns:
- number return value
- 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:
- number FD of temporary file (-1 on error)
- string or errno Filename of temporary file or errno on error
Special file creation
- mkdir(path, mode)
-
Create a directory.
Parameters:
- path string
- mode number
Returns:
- number return value
- errno
- mkfifo(path, mode)
-
Make a FIFO special file (a named pipe)
Parameters:
- path string
- mode number
Returns:
- number return value
- errno
File removal
- unlink(path)
-
Delete a name and possibly the file it points to.
Parameters:
- path string
Returns:
- number return value
- errno
- rmdir(path)
-
Delete a directory.
Parameters:
- path string
Returns:
- number return value
- errno
- rename(oldpath, newpath)
-
Change the name or location of a file.
Parameters:
Returns:
- number return value
- 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:
- path string
Returns:
- number return value
- errno or stat-table
- fstat(fd)
-
Get file status by fd.
Parameters:
- fd number
Returns:
- number return value
- errno or stat-table
- lstat(path)
-
Get symlink status by path.
Parameters:
- path string to symlink
Returns:
- number return value
- 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:
- path string
- mode number
Returns:
- number return value
- errno
- chmod(fd, mode)
-
Change permissions of a file by fd.
Parameters:
- fd number
- mode number
Returns:
- number return value
- errno
- chmod(path, owner, group)
-
Change ownership of a file.
Parameters:
- path string
- owner number
- group number
Returns:
- number return value
- errno
- ftruncate(fd, lenght)
-
Truncate a file to a specified length.
Parameters:
- fd number
- lenght number
Returns:
- number return value
- errno
Pipes
- pipe(pipe)
-
Create pipe.
Parameters:
- pipe table A table for which this function will fill in the keys 1 and 2
Returns:
- number return value
- 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:
- number return value
- 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:
- number return value
- errno
File descriptor manipulation
- dup(oldfd)
-
Duplicate a file descriptor.
Parameters:
- oldfd number
Returns:
- number return value
- errno
- dup2(oldfd, newfd)
-
Duplicate a file descriptor to a specific one
Parameters:
- oldfd number
- newfd number
Returns:
- number return value
- 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:
- number return value
- errno
File descriptor deassignment
Input and output
- read(fd, count)
-
Read from a file descriptor.
Parameters:
- fd number
- count number
Returns:
- number or string return value or read data
- errno
- write(fd, data[, start_offset=0])
-
Write to a file descriptor.
Parameters:
- fd number
- data string
- start_offset number (default 0)
Returns:
- number return value
- errno
- writev(fd, ...)
-
Write data from multiple buffers.
Parameters:
- fd number
- ... string
Returns:
- number return value
- 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:
- number return value
- 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:
- number return value
- 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:
- number return value
- 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:
- number return value
- errno
File synchronisation
- fsync(fd)
-
Synchronise a file’s in-core state with storage device.
Parameters:
- fd number
Returns:
- number return value
- errno
- fdatasync(fd)
-
Synchronise only a file’s data and not unnessercery metadata.
Not available on all systems.
Parameters:
- fd number
Returns:
- number return value
- errno
General Terminal Interface
- tcgetpgrp(fd)
-
Get terminal forground process group.
Parameters:
- fd number
Returns:
- number return value
- errno
- tcsetpgrp(fd, pgrp_id)
-
Set terminal forground process group.
Parameters:
- fd number
- pgrp_id number
Returns:
- number return value
- errno
Clock and timer functions
- nanosleep(seconds, nanoseconds)
-
High-resolution sleep.
Parameters:
- seconds number
- nanoseconds number
Returns:
- number return value
- errno
- number remaining seconds
- 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:
- mq or number message queue, or return value
- errno
- mq_close(mqdes)
-
Close a message queue descriptor.
Parameters:
- mqdes mq
Returns:
- number return value
- errno
- mq_unlink(name)
-
Remove a message queue.
Parameters:
- name string
Returns:
- number return value
- errno
- mq_send(queue, message, priority)
-
Send a message to a message queue.
Parameters:
- queue mq
- message string
- priority number
Returns:
- number return value
- errno
- mq_receive(queue)
-
Receive a message from a message queue.
Parameters:
- queue mq
Returns:
- number return value
- errno
- string or nil message data, or nil in case of error
- 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:
- number return value
- errno
- mqattr-table new attribute table
- mq_getattr(mqdes)
-
Get message queue attributes.
Parameters:
- mqdes mq
Returns:
- number return value
- errno
- 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:
- number return value
- 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:
- number return value
- errno
- string or nil message data, or nil in case of error
- 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. Usegetaddrinfo()
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:
- number return value
- errno
- listen(sockfd, backlog)
-
Listen for connections on a socket.
Parameters:
- sockfd number
- backlog number
Returns:
- number return value
- errno
- shutdown(sockfd, how)
-
Shut down part of a full-duplex connection.
Parameters:
- sockfd number
- how number
Returns:
- number return value
- errno
- connect(fd, sockaddr)
-
Initiate a connection on a socket.
Parameters:
- fd number
- sockaddr sockaddr
Returns:
- number return value
- errno
- bind(fd, sockaddr)
-
Bind a name to a socket.
Parameters:
- fd number
- sockaddr sockaddr
Returns:
- number return value
- errno
- accept(fd)
-
Accept a connection on a socket.
Parameters:
- fd number
Returns:
- number return value
- errno or sockaddr
- getsockopt(fd, level, optname)
-
Get options on a socket.
Parameters:
- fd number
- level number
- optname number
Returns:
- number return value
- errno, number or string
- setsockopt(fd, level, optname, optvalue)
-
Set an option on a socket.
Parameters:
- fd number
- level number
- optname number
- optvalue
Returns:
- number return value
- 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:
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:
- number return value
- 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:
- number return value
- errno
- recv(fd, count[, flags=0])
-
Receive a message from a socket.
Parameters:
- fd number
- count number
- flags number (default 0)
Returns:
- number or string return value if error, otherwise string
- 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:
- number or string return value if error, otherwise string
- errno
- 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:
- timeval or number return value
- errno
Misc utility functions
- strerror(errno)
-
Return a string describing an error number.
Parameters:
- errno errno
Returns:
- 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:
- iconv or number return value
- errno
- iconv_close(handle)
-
Close a previously-allocated iconv descriptor.
Parameters:
- handle iconv
Returns:
- number return vlaue
- errno
- iconv(handle, buf)
-
Perform character set conversion.
Parameters:
Returns: