Module lposix

Functions

abort () Abort the program immediately.
raise (nsig) Raise a signal on this process.
isgraph (character) Check for any printable character except space.
isprint (character) Check for any printable character including space.
errno (n) Describe an error code/and or read errno
set_errno (n) Set errno.
realpath (path) Find canonicalized absolute pathname.
basename (path) File part of path.
dirname (path) Directory name of path.
dir (path) Contents of directory.
fnmatch (pat, name, flags) Match a filename against a shell pattern.
glob (pat) Find all files in this directory matching a shell pattern.
files (path) Iterator over all files in this directory.
getcwd () Current working directory for this process.
mkdir (path) Make a directory.
chdir (path) Set the working directory.
rmdir (path) Remove a directory.
unlink (path) Unlink a file.
link (target, link, soft) Create a link.
readlink (path) Read value of a symbolic link.
access (path, mode) Check real user’s permissions for a file.
fileno (file) File descriptor corresponding to a Lua file object.
mkfifo (path) Make a FIFO pipe.
mkstemp (templ) Create a unique temporary file.
mkdtemp (templ) Create a unique temporary directory.
exec (path, ..., t) Execute a program without using the shell.
execp (path, ..., t) Execute a program using the shell.
fork () Fork this program.
_exit (return) Terminate the calling process.
rpoll (file, timeout) Wait for some event on a file descriptor.
poll (list, timeout) Wait for events on multiple file descriptors.
wait (pid) Wait for the given process.
kill (pid, sig) Send a signal to the given process.
killpg (pgrp, sig) Send a signal to the given process group.
setpid (what, id, gid) Set the uid, euid, gid, egid, sid or pid & gid.
sleep (seconds) Sleep for a number of seconds.
nanosleep (seconds, nanoseconds) Sleep with nanosecond precision.
msgget (key, flags, mode) Get a message queue identifier
msgsnd (id, type, message, flags) Send message to a message queue
msgrcv (id, size, type, flags) Receive message from a message queue
setenv (name, value, over) Set an environment variable for this process.
getenv (name) Get value of environment variable, or all variables.
umask (mode) Set file mode creation mask.
openpt (oflags) Open a pseudoterminal.
grantpt (file) Grant access to a slave pseudoterminal
unlockpt (file) Unlock a pseudoterminal master/slave pair
ptsname (file) Get the name of a slave pseudo-terminal
open (path, oflags, mode) Open a file.
close (fd) Close an open file descriptor.
dup (fd) Duplicate an open file descriptor.
dup2 (oldfd, newfd) Duplicate one open file descriptor to another, closing the new one if necessary.
pipe () Creates a pipe.
chmod (path, mode) Change the mode of the path.
read (fd, count) Read bytes from a file.
write (fd, buf) Write bytes to a file.
chown (path, uid, gid) Change ownership of a file.
utime (path, mtime, atime) Change file last access and modification times.
getpid (...) Get process identifiers.
hostid () Get host id.
ttyname (fd) Name of a terminal device.
ctermid () Name of controlling terminal.
getpasswd (user, ...) Get the password entry for a user.
getgroup (group) Information about a group.
getgroups () Get list of supplementary group IDs.
times (...) Get the current process times.
stat (path, ...) Information about an existing file path.
statvfs (path, ...) Get file system statistics.
fcntl (fd, cmd, arg) Manipulate file descriptor.
isatty (fd) Test whether a file descriptor refers to a terminal.
uname (optional) Return information about this machine.
pathconf (path, ...) Get a value for a configuration option for a filename.
sysconf (...) Get configuration information at runtime.
openlog (ident, option, facility) Open the system logger.
syslog (priority, message) Write to the system logger.
closelog () Close system log.
setlogmask (bitwise) Set log priority mask.
crypt (string, salt) Encrypt a password.
setrlimit (resource, softlimit, hardlimit) Set a resource limit for subsequent child processes.
getrlimit (resource) Get resource limits for this process.

Time and date

gettimeofday () Get time of day.
time () Get current time.
localtime (t) Convert time in seconds to table.
gmtime (t) Convert UTC time in seconds to table.
clock_getres (name) Find the precision of a clock.
clock_gettime (name) Read a clock.
strftime (tm) Write a time out according to a format.
strptime (s, format) Parse a date string.
mktime (tm) Convert a time table into a time value.
getopt (arg, shortopts, longopts) Parse command-line options.
signal (signum, handler, flags) Install a signal handler for this signal number.
sync () commit buffer cache to disk
fsync (fd) synchronize a file’s in-core state with storage device
fdatasync (fd) synchronize a file’s in-core state with storage device without metadata
lseek (fd, offset, whence) reposition read/write file offset
nice (inc) change process priority


Functions

abort ()
Abort the program immediately.

See also:

raise (nsig)
Raise a signal on this process.

Parameters:

  • nsig int

Returns:

    integer error code

See also:

isgraph (character)
Check for any printable character except space.

Parameters:

Returns:

    true if character is in the class

See also:

isprint (character)
Check for any printable character including space.

Parameters:

Returns:

    true if character is in the class

See also:

errno (n)
Describe an error code/and or read errno

Parameters:

  • n int optional error code (default: current value of errno )

Returns:

  1. description
  2. error code

See also:

set_errno (n)
Set errno.

Parameters:

  • n int error code

See also:

realpath (path)
Find canonicalized absolute pathname.

Parameters:

Returns:

  1. canonicalized absolute path, or nil on error
  2. error message if failed

See also:

basename (path)
File part of path.

Parameters:

Returns:

    file part

See also:

dirname (path)
Directory name of path.

Parameters:

Returns:

    directory part

See also:

dir (path)
Contents of directory.

Parameters:

  • path string optional (default .)

Returns:

    contents as table

See also:

fnmatch (pat, name, flags)
Match a filename against a shell pattern.

Parameters:

  • pat string shell pattern
  • name string filename
  • flags int optional (default 0)

Returns:

    true or false

Raises:

error if fnmatch failed

See also:

glob (pat)
Find all files in this directory matching a shell pattern.

Parameters:

Returns:

    table of matching filenames

See also:

files (path)
Iterator over all files in this directory.

Parameters:

  • path string optional (default .)

Returns:

    an iterator
getcwd ()
Current working directory for this process.

Returns:

    path

See also:

mkdir (path)
Make a directory.

Parameters:

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed.

See also:

chdir (path)
Set the working directory.

Parameters:

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed.

See also:

Usage:

    status, errstr, errno = posix.access("/etc/passwd", "rw")
rmdir (path)
Remove a directory.

Parameters:

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed.

See also:

unlink (path)
Unlink a file.

Parameters:

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed.

See also:

link (target, link, soft)
Create a link.

Parameters:

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed.

See also:

readlink (path)
Read value of a symbolic link.

Parameters:

Returns:

  1. link target on success, error otherwise
  2. error message if failed

See also:

access (path, mode)
Check real user’s permissions for a file.

Parameters:

  • path string
  • mode string optional, can contain ‘r’,‘w’,‘x’ and ‘f’ (default ‘f’)

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed.

See also:

Usage:

    status, errstr, errno = posix.access("/etc/passwd", "rw")
fileno (file)
File descriptor corresponding to a Lua file object.

Parameters:

  • file Lua file object

Returns:

  1. handle on success, nil otherwise
  2. error message if failed.
mkfifo (path)
Make a FIFO pipe.

Parameters:

Returns:

  1. handle on success, nil otherwise
  2. error message if failed.

See also:

mkstemp (templ)
Create a unique temporary file.

Parameters:

  • templ string pattern that ends in “XXXXXX”

Returns:

  1. file descriptor, nil otherwise
  2. name on success, error otherwise

See also:

Usage:

    posix.mkstemp 'wooXXXXXX'
mkdtemp (templ)
Create a unique temporary directory.

Parameters:

  • templ string pattern that ends in six ‘X’ characters

Returns:

  1. path on success, nil otherwise
  2. error message if failed

See also:

exec (path, ..., t)
Execute a program without using the shell.

Parameters:

  • path string
  • ... any arguments, or
  • t table of arguments (can include index 0)

Returns:

  1. return code, nil otherwise
  2. error message if failed.

See also:

execp (path, ..., t)
Execute a program using the shell.

Parameters:

  • path string
  • ... any arguments, or
  • t table of arguments (can include index 0)

Returns:

  1. return code, nil otherwise
  2. error message if failed.

See also:

fork ()
Fork this program.

Returns:

  1. return code, nil otherwise
  2. error message if failed.

See also:

_exit (return)
Terminate the calling process.

Parameters:

  • return int status

See also:

rpoll (file, timeout)
Wait for some event on a file descriptor. Adapted from http://lua-users.org/lists/lua-l/2007-11/msg00346.html

Parameters:

  • file int descriptor
  • timeout int

Returns:

  1. return code, nil otherwise
  2. error message if failed.

See also:

poll (list, timeout)
Wait for events on multiple file descriptors.

Parameters:

  • list of file descriptors
  • timeout int optional (default -1)

Returns:

  1. return code, nil otherwise
  2. error message if failed.

See also:

wait (pid)
Wait for the given process.

Parameters:

  • pid int optional (default -1 (any child process))

Returns:

  1. pid of terminated child, nil on error
  2. how child ended (“exited”, “killed” or “stopped”), or error message on error.
  3. status value (computed with WEXITSTATUS, WTERMSIG or WSTOPSIG as appropriate), or nothing on error.

See also:

kill (pid, sig)
Send a signal to the given process.

Parameters:

  • pid int process id
  • sig int optional (default SIGTERM)

Returns:

  1. return code, nil otherwise
  2. error message if failed.

See also:

killpg (pgrp, sig)
Send a signal to the given process group.

Parameters:

  • pgrp int group id
  • sig int optional (default SIGTERM)

Returns:

  1. return code, nil otherwise
  2. error message if failed.

See also:

setpid (what, id, gid)
Set the uid, euid, gid, egid, sid or pid & gid.

Parameters:

  • what string one of ‘u’, ‘U’, ‘g’, ‘G’, ’s', ‘p’ (upper-case means “effective”)
  • id (uid, gid or pid for every value of what except ’s')
  • gid (only for what value ‘p’)

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed

See also:

sleep (seconds)
Sleep for a number of seconds.

Parameters:

  • seconds int

Returns:

    code

See also:

nanosleep (seconds, nanoseconds)
Sleep with nanosecond precision.

Parameters:

  • seconds int
  • nanoseconds int

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed, or the remaining time as two results tv_sec, tv_nsec if return value is EINTR.

See also:

msgget (key, flags, mode)
Get a message queue identifier

Parameters:

  • key int
  • flags int (optional, default - 0)
  • mode int (optional, default - 0777)

Returns:

  1. message queue identifier on success
  2. nil and error message if failed

See also:

msgsnd (id, type, message, flags)
Send message to a message queue

Parameters:

  • id int
    • message queue identifier returned by msgget
  • type int
    • message type
  • message string
  • flags int (optional, default - 0)

Returns:

  1. 0 on success
  2. nil and error message if failed

See also:

msgrcv (id, size, type, flags)
Receive message from a message queue

Parameters:

  • id int
    • message queue identifier returned by msgget
  • size int
    • maximum message size
  • type int
    • message type (optional, default - 0)
  • flags int (optional, default - 0)

Returns:

  1. message type and message text on success
  2. nil, nil and error message if failed

See also:

setenv (name, value, over)
Set an environment variable for this process. (Child processes will inherit this)

Parameters:

  • name string
  • value string (maybe nil, meaning ‘unset’)
  • over non-nil prevents overwriting a variable

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed.

See also:

getenv (name)
Get value of environment variable, or all variables.

Parameters:

Returns:

    value if name given, otherwise a name-indexed table of values.

See also:

Usage:

    for a,b in pairs(posix.getenv()) do print(a, b) end
umask (mode)
Set file mode creation mask.

Parameters:

  • mode string optional file creation mask string (default current mask; see chmod for format)

Returns:

    previous umask

See also:

openpt (oflags)
Open a pseudoterminal.

Parameters:

  • oflags int bitwise OR of the values O_RDWR, and possibly O_NOCTTY (all in the library’s namespace)

Returns:

  1. file descriptor on success, nil otherwise
  2. error message if failed.

See also:

grantpt (file)
Grant access to a slave pseudoterminal

Parameters:

  • file descriptor returned by opening /dev/ptmx

Returns:

  1. 0 on success
  2. nil, error message if failed.

See also:

unlockpt (file)
Unlock a pseudoterminal master/slave pair

Parameters:

  • file descriptor returned by opening /dev/ptmx

Returns:

  1. 0 on success
  2. nil, error message if failed.

See also:

ptsname (file)
Get the name of a slave pseudo-terminal

Parameters:

  • file descriptor returned by opening /dev/ptmx

Returns:

  1. path name of the slave terminal device
  2. nil, error message if failed.

See also:

open (path, oflags, mode)
Open a file.

Parameters:

  • path string
  • oflags int bitwise OR of the values O_RDONLY, O_WRONLY, O_RDWR, O_APPEND, O_CREAT, O_DSYNC, O_EXCL, O_NOCTTY, O_NONBLOCK, O_RSYNC, O_SYNC, O_TRUNC (all in the library’s namespace)
  • mode string (used with O_CREAT; see chmod for format)

Returns:

  1. file descriptor on success, nil otherwise
  2. error message if failed.

See also:

close (fd)
Close an open file descriptor.

Parameters:

  • fd int

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed.

See also:

dup (fd)
Duplicate an open file descriptor.

Parameters:

  • fd int

Returns:

  1. file descriptor on success, nil otherwise
  2. error message if failed.

See also:

dup2 (oldfd, newfd)
Duplicate one open file descriptor to another, closing the new one if necessary.

Parameters:

  • oldfd int
  • newfd int

Returns:

  1. new file descriptor on success, nil otherwise
  2. error message if failed.

See also:

pipe ()
Creates a pipe.

Returns:

  1. fd read end
  2. fd write end

See also:

chmod (path, mode)
Change the mode of the path. Modes are specified in one of the following formats: “rwxrwxrwx” (e.g. “rw-rw-w–”) “ugoa+-=rwx” (e.g. “u+w”) “+-=rwx” (e.g. “+w”)

Parameters:

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed.

See also:

Usage:

    posix.chmod('bin/dof','+x')
read (fd, count)
Read bytes from a file.

Parameters:

  • fd int the file descriptor
  • count int number of bytes to read

Returns:

  1. string with at most count bytes, or nil on error
  2. error message if failed

See also:

write (fd, buf)
Write bytes to a file.

Parameters:

  • fd int the file descriptor
  • buf string containing bytes

Returns:

  1. number of bytes written on success, nil otherwise
  2. error message if failed.

See also:

chown (path, uid, gid)
Change ownership of a file.

Parameters:

  • path string existing file path
  • uid (string or number)
  • gid (string or number)

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed.

See also:

Usage:

    print(posix.chown("/etc/passwd",100,200)) -- will fail for a normal user, and hence print an error
utime (path, mtime, atime)
Change file last access and modification times.

Parameters:

  • path string existing file path
  • mtime int optional modification time (default current time)
  • atime int optional access time (default current time)

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed.

See also:

getpid (...)
Get process identifiers.

Parameters:

  • ... string types, each one of “egid”, “euid”, “gid”, “uid”, “pgrp”, “pid”, “ppid”

Returns:

    … values, or table of all ids if no option given

Usage:

    posix.getpid 'pid' -- PID of current process
hostid ()
Get host id.

Returns:

    host id

See also:

ttyname (fd)
Name of a terminal device.

Parameters:

  • fd int optional file descriptor (default 0)

Returns:

    string name

See also:

ctermid ()
Name of controlling terminal.

Returns:

    code

See also:

getpasswd (user, ...)
Get the password entry for a user.

Parameters:

  • user (name or id)
  • ... string field names, each one of “uid”, “name”, “gid”, “passwd”, “dir”, “shell”

Returns:

    … values, or table of all fields if no option given

Usage:

  • for a,b in pairs(posix.getpasswd("root")) do print(a,b) end
  • print(posix.getpasswd("root", "shell"))
getgroup (group)
Information about a group.

Parameters:

  • group id or name

Returns:

    table {name=name,gid=gid,0=member0,1=member1,…}
getgroups ()
Get list of supplementary group IDs.

Returns:

    table of group IDs.

See also:

times (...)
Get the current process times.

Parameters:

  • ... string field names, each one of “utime”, “stime”, “cutime”, “cstime”, “elapsed”

Returns:

    … times, or table of all times if no option given

See also:

stat (path, ...)
Information about an existing file path.

Parameters:

  • path string file path
  • ... string field names, each one of “mode”, “ino”, “dev”, “nlink”, “uid”, “gid”, “size”, “atime”, “mtime”, “ctime”, “type”

Returns:

    … values, or table of all fields if no option given

See also:

Usage:

    for a, b in pairs(posix.stat("/etc/")) do print(a, b) end
statvfs (path, ...)
Get file system statistics.

Parameters:

  • path string any path within the mounted file system
  • ... string field names, each one of “bsize”, “frsize”, “blocks”, “bfree”, “bavail”, “files”, “ffree”, “favail”, “fsid”, “flag”, “namemax”

Returns:

    … values, or table of all fields if no option given

See also:

fcntl (fd, cmd, arg)
Manipulate file descriptor.

Parameters:

  • fd int file descriptor to act on
  • cmd int operation to perform
  • arg int optional (default 0)

Returns:

  1. integer return value depending on cmd, or nil on error
  2. error message if failed

See also:

isatty (fd)
Test whether a file descriptor refers to a terminal.

Parameters:

  • fd int file descriptor to test

Returns:

  1. 1 if fd is an open file descriptor referring to a terminal, or nil otherwise
  2. error message if failed

See also:

uname (optional)
Return information about this machine.

Parameters:

  • optional string , contains zero or more of: %m machine name %n node name %r release %s sys name %v version

    (default return all information available)

Returns:

  1. information string on success, nil otherwise
  2. error message if failed

See also:

pathconf (path, ...)
Get a value for a configuration option for a filename.

Parameters:

  • path string optional (default “.”)
  • ... string field names, each one of “LINK_MAX”, “MAX_CANON”, “NAME_MAX”, “PIPE_BUF”, “CHOWN_RESTRICTED”, “NO_TRUNC”, “VDISABLE”

Returns:

    … values, or table of all fields if no option given

See also:

Usage:

    for a, b in pairs(posix.pathconf("/dev/tty")) do print(a, b) end
sysconf (...)
Get configuration information at runtime.

Parameters:

  • ... string field names, each one of “ARG_MAX”, “CHILD_MAX”, “CLK_TCK”, “NGROUPS_MAX”, “STREAM_MAX”, “TZNAME_MAX”, “OPEN_MAX”, “JOB_CONTROL”, “VERSION”

Returns:

    … values, or table of all fields no option

See also:

openlog (ident, option, facility)
Open the system logger.

Parameters:

  • ident string all messages will start with this
  • option string optional, any combination of ‘c’ (directly to system console if an error sending), ‘n’ (no delay) or ‘p’ (show PID)
  • facility int optional (default LOG_USER)

See also:

syslog (priority, message)
Write to the system logger.

Parameters:

  • priority int one of these values: 1 Alert - immediate action 2 Critcal 3 Error 4 Warning 5 Notice 6 Informational
  • message string

See also:

closelog ()
Close system log.

See also:

setlogmask (bitwise)
Set log priority mask.

Parameters:

  • bitwise int OR of values from LOG_EMERG, LOG_ALERT, LOG_CRIT, LOG_WARNING, LOG_NOTICE, LOG_INFO, LOG_DEBUG

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed.
crypt (string, salt)
Encrypt a password. Not recommended for general encryption purposes.

Parameters:

  • string string
  • salt string two-character string from [a-zA-Z0-9./]

Returns:

    encrypted string

See also:

setrlimit (resource, softlimit, hardlimit)
Set a resource limit for subsequent child processes.

Parameters:

  • resource string one of “core”, “cpu”, “data”, “fsize”, “nofile”, “stack”, “as”
  • softlimit optional (default keep current limit)
  • hardlimit optional (default keep current limit)

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed.

See also:

Usage:

    posix.setrlimit("nofile", 1000, 2000)
getrlimit (resource)
Get resource limits for this process.

Parameters:

  • resource string one of “core”, “cpu”, “data”, “fsize”, “nofile”, “stack”, “as”

Returns:

  1. softlimit, or nil if error
  2. hardlimit, or message on error

Time and date

gettimeofday ()
Get time of day.

Returns:

  1. time in seconds
  2. remainder in nanoseconds

See also:

time ()
Get current time.

Returns:

    time in seconds since epoch
localtime (t)
Convert time in seconds to table.

Parameters:

  • t time in seconds since epoch (default now)

Returns:

    time table: contains “is_dst”,“yearday”,“hour”,“min”,“year”,“month”, “sec”,“weekday”,“monthday”, “day” (the same as “monthday”)
gmtime (t)
Convert UTC time in seconds to table.

Parameters:

  • t time in seconds since epoch (default now)

Returns:

    time table as in localtime
clock_getres (name)
Find the precision of a clock.

Parameters:

  • name string of clock, one of “monotonic”, “process_cputime_id”, or “thread_cputime_id”, or nil for realtime clock.

Returns:

  1. seconds, or nil on error
  2. nanoseconds, or message on error
clock_gettime (name)
Read a clock.

Parameters:

  • name string of clock, one of “monotonic”, “process_cputime_id”, or “thread_cputime_id”, or nil for realtime clock.

Returns:

  1. seconds, or nil on error
  2. nanoseconds, or message on error
strftime (tm)
Write a time out according to a format.

Parameters:

  • tm optional time table (e.g from localtime ; default current time)

See also:

strptime (s, format)
Parse a date string.

Parameters:

Returns:

  1. time table, like localtime
  2. next index of first character not parsed as part of the date

See also:

Usage:

    posix.strptime('20','%d').monthday == 20
mktime (tm)
Convert a time table into a time value.

Parameters:

Returns:

    time in seconds since epoch
getopt (arg, shortopts, longopts)
Parse command-line options.

Parameters:

  • arg command line arguments
  • shortopts string e.g ‘ho:v’ (colon means ‘receives argument’)
  • longopts e.g. {{‘help’,‘none’,2},…}

See also:

Usage:

    for ret, longindex, optind, optarg in posix.getopt (arg, shortopts[, longopts[, opterr[, optind]]]) do ... end
signal (signum, handler, flags)
Install a signal handler for this signal number. N.B. Although this is the same API as signal(2), it uses sigaction for guaranteed semantics.

Parameters:

  • signum int
  • handler function
  • flags optional the sa_flags element of struct sigaction

Returns:

    previous handler function

See also:

sync ()
commit buffer cache to disk

See also:

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

Parameters:

  • fd int

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed.

See also:

fdatasync (fd)
synchronize a file’s in-core state with storage device without metadata

Parameters:

  • fd int

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed.

See also:

lseek (fd, offset, whence)
reposition read/write file offset

Parameters:

  • fd int
  • offset int
  • whence int one of SEEK_SET, SEEK_CUR or SEEK_END

Returns:

  1. new offset on success, nil otherwise
  2. error message if failed.

See also:

nice (inc)
change process priority

Parameters:

  • inc int adds inc to the nice value for the calling process

Returns:

  1. new nice value on success, nil otherwise
  2. error message if failed.

See also:

generated by LDoc 1.4.2