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.
getpid() |
Get process identification. |
getppid() |
Get process’s parent’s identification. |
uname-table |
uname() information table. |
uname() |
Get name and information about current kernel. |
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. |
fsync(fd) |
Synchronise a file’s in-core state with storage device. |
fdatasync(fd) |
Synchronise only a file’s data and not unnessercery metadata. |
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(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. |
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. |
Process creation and execution
Functions to do with the creation of new processes and the execution of other
programs.
-
fork()
-
Create a child process.
Returns:
-
number
return value
-
errno
errno
-
exec(path, ...)
-
Execute a file.
Calls execv().
Parameters:
- path
string
absolute path to executable
- ...
string
parameters to pass to executatable
Returns:
-
number
return value
-
errno
errno
-
execp(path, ...)
-
Execute a file, searching PATH.
Calls execp().
Parameters:
- path
string
name of executable
- ...
string
parameters to pass to executatable
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.
Parameters:
- pid
number
pid to wait on
- options
number
options for call
Returns:
-
number
return value
-
number or errno
status code or errno if error
-
WIFEXITED(status)
-
Check status macro for WIFEXITED.
Parameters:
Returns:
number
true or false
-
WEXITSTATUS(status)
-
Obtain exit status code from child
Parameters:
Returns:
number
exit status code
-
WIFSIGNALLED(status)
-
Check status macro for WIFSIGNALED.
Parameters:
Returns:
number
true or false
-
WTERMSIG(status)
-
Obtain signal used to kill child.
Parameters:
Returns:
number
signal number
-
WCOREDUMP(status)
-
Check status macro for WCOREDUMP.
Parameters:
Returns:
number
true or false
-
WIFSTOPPED(status)
-
Check status macro for WIFSTOPPED.
Parameters:
Returns:
number
true or false
-
WSTOPSIG(status)
-
Obtain signal number used to stop child.
Parameters:
Returns:
number
signal number
-
WIFCONTINUED(status)
-
Check status macro for WIFCONTINUED.
Linux 2.6.10.
Parameters:
Returns:
number
true or false
-
_exit([exit=0])
-
Terminate calling process. Does not return.
Parameters:
- exit
number
status code.
(default 0)
Signals
Functions related to sending signals.
-
kill(pid, signal)
-
Send signal to a process.
Parameters:
- pid
number
signal destination
- signal
number
signal to send
Returns:
-
number
return value
-
errno
errno
Timer operations
-
alarm(seconds)
-
Set an alarm clock for delivery of a signal.
Parameters:
- seconds
number
How long to wait before signal delivery
Returns:
number
return value
-
pause()
-
Wait for a signal.
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:
number
pid
-
getppid()
-
Get process’s parent’s identification.
Returns:
number
pid
User identification
-
getuid()
-
Get user identity.
Returns:
number
uid
-
geteuid()
-
Get effective user identity.
Returns:
number
uid
-
getgid()
-
Get group identity.
Returns:
number
gid
-
getegid()
-
Get effective group identity.
Returns:
number
gid
-
setuid(uid)
-
Set user identity.
Parameters:
Returns:
-
number
return value
-
errno
errno
-
setgid(gid)
-
Set group identity
Parameters:
Returns:
-
number
return value
-
errno
errno
-
getlogin()
-
Get username.
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
-
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.
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.
Parameters:
Returns:
string or nil
return value
-
setenv(name, value[, overwrite=0])
-
Set an environment variable.
Parameters:
Returns:
-
number
return value
-
errno
-
unsetenv(name)
-
Unsets an environment variable.
Parameters:
Returns:
-
number
return value
-
errno
Directories
readdir() is a hideous API. As such, we need to be reasonably high-level here,
otherwise everything is just too painful.
-
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
-
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:
Working directory
-
chdir(path)
-
Change working directory.
Parameters:
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.
Parameters:
- path
string
- flags
number
- mode
number
, must be specified if creating.
-
umask(mask)
-
Set file mode creation mask.
Parameters:
-
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:
Returns:
-
number
return value
-
string or errno
value, or errno on error
Special file creation
-
mkdir(path, mode)
-
Create a directory.
Parameters:
Returns:
-
number
return value
-
errno
-
mkfifo(path, mode)
-
Make a FIFO special file (a named pipe)
Parameters:
Returns:
-
number
return value
-
errno
File removal
-
unlink(path)
-
Delete a name and possibly the file it points to.
Parameters:
Returns:
-
number
return value
-
errno
-
rmdir(path)
-
Delete a directory.
Parameters:
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:
Returns:
-
number
return value
-
errno or stat-table
-
fstat(fd)
-
Get file status by fd.
Parameters:
Returns:
-
number
return value
-
errno or stat-table
-
lstat(path)
-
Get symlink status by path.
Parameters:
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:
Returns:
-
number
return value
-
errno
-
chmod(fd, mode)
-
Change permissions of a file by fd.
Parameters:
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:
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:
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
-
close(fd)
-
Close a file descriptor.
Parameters:
Returns:
-
number
return value
-
errno
Input and output
-
read(fd, count)
-
Read from a file descriptor.
Parameters:
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:
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
-
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:
Returns:
-
number
return value
-
errno
-
fdatasync(fd)
-
Synchronise only a file’s data and not unnessercery metadata.
Not available on all systems.
Parameters:
Returns:
-
number
return value
-
errno
General Terminal Interface
-
tcgetpgrp(fd)
-
Get terminal forground process group.
Parameters:
Returns:
-
number
return value
-
errno
-
tcsetpgrp(fd, pgrp_id)
-
Set terminal forground process group.
Parameters:
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
Returns:
-
mq or number
message queue, or return value
-
errno
-
mq_close(mqdes)
-
Close a message queue descriptor.
Parameters:
Returns:
-
number
return value
-
errno
-
mq_unlink(name)
-
Remove a message queue.
Parameters:
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:
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:
Returns:
-
number
return value
-
errno
-
mqattr-table
new attribute table
-
mq_getattr(mqdes)
-
Get message queue attributes.
Parameters:
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. 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:
-
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:
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:
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:
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:
-
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:
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
-
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:
Returns:
-
number
return vlaue
-
errno
-
iconv(handle, buf)
-
Perform character set conversion.
Parameters:
Returns:
-
string or number
resulting string or return value in case of error
-
errno
-
string or nil
partial result when error.