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.
isgraph (character) Check for any printable character including space.
errno (n) Describe an error code/and or read `errno`
set_errno (n) Set errno.
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, ...) Execute a program without using the shell.
execp (path, ...) 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.
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.
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.
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.
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_getres (name) Read a clock.
strftime (tm) Write a time out according to a format.
mktime (tm) Convert a time table into a time value.
getopt_long (arg, shortopts, longopts) Parse command-line options.
signal (signum, handler) Install a signal handler for this signal number.


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:

isgraph (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:

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:

  • path

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, ...)
Execute a program without using the shell.

Parameters:

  • path string
  • ... any arguments

Returns:

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

see also:

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

Parameters:

  • path string
  • ... any arguments

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. return code, nil otherwise
  2. error message if failed.

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:

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. results `tv_sec`, `tv_nsec` if return value is `EINTR`.

Parameters:

  • seconds int
  • nanoseconds int

Returns:

  1. 0 on success, nil otherwise
  2. error message if failed, or the remaining time as two

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:

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:

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:

    string with at most `count` bytes.

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. "files", "ffree", "favail", "fsid", "flag", "namemax"

Parameters:

  • path string any path within the mounted file system
  • ... field names, each one of "bsize", "frsize", "blocks", "bfree", "bavail",

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. "sec","weekday","monthday", "day" (the same as "monthday")

Parameters:

  • t time in seconds since epoch (default now)

Returns:

    time table: contains "is_dst","yearday","hour","min","year","month",
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_getres (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:

mktime (tm)
Convert a time table into a time value.

Parameters:

  • tm time table as in `localtime`

Returns:

    time in seconds since epoch
getopt_long (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_long (arg, shortopts, longopts, opterr, optind) do ... end
signal (signum, handler)
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

Returns:

    previous handler function

see also:

generated by LDoc 1.3