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.
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.

Parameters:

nsig int

Returns:

integer error code

Parameters:

character string to check

Returns:

true if character is in the class

Parameters:

character string to check

Returns:

true if character is in the class

Parameters:

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

Returns:

description
error code

Parameters:

n int error code

Parameters:

path string

Returns:

canonicalized absolute path, or nil on error
error message if failed

Parameters:

path string

Returns:

file part

Parameters:

path string

Returns:

directory part

Parameters:

path string optional (default .)

Returns:

contents as table

Parameters:

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

Returns:

true or false

Raises:

error if fnmatch failed

Parameters:

pat string shell pattern

Returns:

table of matching filenames

Parameters:

path string optional (default .)

Returns:

an iterator

getcwd ()

Current working directory for this process.

Returns:

path

Parameters:

path string

Returns:

0 on success, nil otherwise
error message if failed.

Parameters:

path string

Returns:

0 on success, nil otherwise
error message if failed.

Usage:

status, errstr, errno = posix.access("/etc/passwd", "rw")

rmdir (path)

Remove a directory.

Parameters:

path string

Returns:

0 on success, nil otherwise
error message if failed.

Parameters:

path string

Returns:

0 on success, nil otherwise
error message if failed.

Parameters:

target string name
link string name
soft bool link

Returns:

0 on success, nil otherwise
error message if failed.

Parameters:

path string

Returns:

link target on success, error otherwise
error message if failed

Parameters:

path string
mode string optional, can contain 'r','w','x' and 'f' (default 'f')

Returns:

0 on success, nil otherwise
error message if failed.

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:

handle on success, nil otherwise
error message if failed.

mkfifo (path)

Make a FIFO pipe.

Parameters:

path string

Returns:

handle on success, nil otherwise
error message if failed.

Parameters:

templ string pattern that ends in "XXXXXX"

Returns:

file descriptor, nil otherwise
name on success, error otherwise

Usage:

posix.mkstemp 'wooXXXXXX'

mkdtemp (templ)

Create a unique temporary directory.

Parameters:

templ string pattern that ends in six 'X' characters

Returns:

path on success, nil otherwise
error message if failed

Parameters:

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

Returns:

return code, nil otherwise
error message if failed.

Parameters:

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

Returns:

return code, nil otherwise
error message if failed.

Returns:

return code, nil otherwise
error message if failed.

Parameters:

return int status

Parameters:

file int descriptor
timeout int

Returns:

return code, nil otherwise
error message if failed.

Parameters:

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

Returns:

return code, nil otherwise
error message if failed.

Parameters:

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

Returns:

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

Parameters:

pid int process id
sig int optional (default SIGTERM)

Returns:

return code, nil otherwise
error message if failed.

Parameters:

pgrp int group id
sig int optional (default SIGTERM)

Returns:

return code, nil otherwise
error message if failed.

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:

0 on success, nil otherwise
error message if failed

Parameters:

seconds int

Returns:

code

Parameters:

seconds int
nanoseconds int

Returns:

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

Parameters:

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

Returns:

message queue identifier on success
nil and error message if failed

Parameters:

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

Returns:

0 on success
nil and error message if failed

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:

message type and message text on success
nil, nil and error message if failed

Parameters:

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

Returns:

0 on success, nil otherwise
error message if failed.

Parameters:

name string if nil, get all

Returns:

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

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

Parameters:

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

Returns:

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

Parameters:

file descriptor returned by opening /dev/ptmx

Returns:

0 on success
nil, error message if failed.

Parameters:

file descriptor returned by opening /dev/ptmx

Returns:

0 on success
nil, error message if failed.

Parameters:

file descriptor returned by opening /dev/ptmx

Returns:

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

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:

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

Parameters:

fd int

Returns:

0 on success, nil otherwise
error message if failed.

Parameters:

fd int

Returns:

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

Parameters:

oldfd int
newfd int

Returns:

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

Returns:

fd read end
fd write end

Parameters:

path string existing file path
mode string

Returns:

0 on success, nil otherwise
error message if failed.

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, or nil on error
error message if failed

Parameters:

fd int the file descriptor
buf string containing bytes

Returns:

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

Parameters:

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

Returns:

0 on success, nil otherwise
error message if failed.

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:

0 on success, nil otherwise
error message if failed.

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

Parameters:

fd int optional file descriptor (default 0)

Returns:

string name

Returns:

code

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.

Parameters:

... string field names, each one of "utime", "stime", "cutime", "cstime", "elapsed"

Returns:

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

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

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

Parameters:

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

Returns:

integer return value depending on `cmd`, or nil on error
error message if failed

Parameters:

fd int file descriptor to test

Returns:

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

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:

information string on success, nil otherwise
error message if failed

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

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

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)

Parameters:

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

Parameters:

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

Returns:

0 on success, nil otherwise
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

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:

0 on success, nil otherwise
error message if failed.

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:

softlimit, or nil if error
hardlimit, or message on error

Time and date

gettimeofday ()

Get time of day.

Returns:

time in seconds
remainder in nanoseconds

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:

seconds, or nil on error
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:

seconds, or nil on error
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)

Parameters:

tm time table as in `localtime`

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},...}`

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

Parameters:

fd int

Returns:

0 on success, nil otherwise
error message if failed.

Parameters:

fd int

Returns:

0 on success, nil otherwise
error message if failed.

Parameters:

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

Returns:

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

Parameters:

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

Returns:

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

luaposix

Contents

Modules

Examples

Module lposix

Functions

Time and date

Functions

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Parameters:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

Raises:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

Returns:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Usage:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Usage:

Parameters:

Returns:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Usage:

Parameters:

Returns:

Module `lposix`