luaposix 36.2.1

• Index

Contents

• Functions
• Constants

Modules

• posix
• posix.ctype
• posix.dirent
• posix.errno
• posix.fcntl
• posix.fnmatch
• posix.glob
• posix.grp
• posix.libgen
• posix.poll
• posix.pwd
• posix.sched
• posix.signal
• posix.stdio
• posix.stdlib
• posix.sys.msg
• posix.sys.resource
• posix.sys.socket
• posix.sys.stat
• posix.sys.statvfs
• posix.sys.time
• posix.sys.times
• posix.sys.utsname
• posix.sys.wait
• posix.syslog
• posix.termio
• posix.time
• posix.unistd
• posix.utime

Examples

• abstract-ns-client.lua
• abstract-ns-server.lua
• dir.lua
• dup2.lua
• fork.lua
• fork2.lua
• getopt.lua
• glob.lua
• limit.lua
• lock.lua
• netlink-uevent.lua
• packet-socket.lua
• ping.lua
• poll.lua
• rt_sched.lua
• signal.lua
• socket.lua
• termios.lua
• tree.lua

Module posix.unistd

Unix Standard APIs.

Where the underlying system does not support one of these functions, it will have a nil value in the module table.

Functions

_exit (status)	Terminate the calling process.
access (path[, mode="f"])	Check real user's permissions for a file.
alarm (seconds)	Schedule an alarm signal.
chdir (path)	Set the working directory.
chown (path, uid, gid)	Change ownership of a file.
close (fd)	Close an open file descriptor.
crypt (trypass, salt)	Encrypt a password.
dup (fd)	Duplicate an open file descriptor.
dup2 (fd, newfd)	Duplicate one open file descriptor to another.
exec (path, argt)	Execute a program at exactly path.
execp (path, argt)	Execute a program found using command PATH search, like the shell.
fdatasync (fd)	Synchronize a file's in-core state with storage device without metadata.
fork ()	Fork this program.
fsync (fd)	Synchronize a file's in-core state with storage device.
ftruncate (fd, length)	Truncate a file to a specified length.
getcwd ()	Current working directory for this process.
getegid ()	Return effective group id of calling process.
geteuid ()	Return effective user id of calling process.
getgid ()	Return group id of calling process.
getgroups ()	Get list of supplementary group ids.
gethostid ()	Get host id.
getopt (arg, opts[, opterr=0[, optind=1]])	Parse command-line options.
getpgrp ()	Return process group id of calling process.
getpid ()	Return process id of calling process.
getppid ()	Return parent process id of calling process.
getuid ()	Return user id of calling process.
isatty (fd)	Test whether a file descriptor refers to a terminal.
lchown (path, uid, gid)	This is like chown, but does not dereference symbolic links.
link (target, link[, soft=false])	Create a link.
linkat (targetdir, target, linkdir, link, flags)	Create a link at specified directory.
lseek (fd, offset, whence)	reposition read/write file offset
nice (inc)	change process priority
pathconf (path, key)	Get a value for a configuration option for a filename.
pipe ()	Creates a pipe.
read (fd, count)	Read bytes from a file.
readlink (path)	Read value of a symbolic link.
rmdir (path)	Remove a directory.
setpid (what, id[, gid])	Set the uid, euid, gid, egid, sid or pid & gid.
sleep (seconds)	Sleep for a number of seconds.
sync ()	Commit buffer cache to disk.
sysconf (key)	Get configuration information at runtime.
tcgetpgrp (fd)	Get id of foreground process group of terminal fd.
tcsetpgrp (fd, pgid)	Make process group pgid the foreground process group of terminal fd.
truncate (path, length)	Truncate a file to a specified length.
ttyname ([fd=0])	Name of a terminal device.
unlink (path)	Unlink a file.
write (fd, buf[, nbytes=#buf[, offset=0]])	Write bytes to a file.

Constants

posix.unistd

Standard constants.

Functions

_exit (status)

Terminate the calling process.

Parameters:

• status int process exit status

See also:

_exit(2)

access (path[, mode="f"])

Check real user's permissions for a file.

Parameters:

• path string file to act on
• mode string can contain 'r','w','x' and 'f' (default "f")

Returns:

int 0, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

access(2)

Usage:

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

alarm (seconds)

Schedule an alarm signal.

Parameters:

• seconds int number of seconds to send SIGALRM in

Returns:

int number of seconds remaining in previous alarm or 0

See also:

alarm(2)

Usage:

local unistd = require "posix.unistd"
seconds = unistd.alarm(10)

chdir (path)

Set the working directory.

Parameters:

• path string file to act on

Returns:

int 0, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

chdir(2)

Usage:

local unistd = require "posix.unistd"
status, errstr, errno = unistd.chdir ("/var/tmp")

chown (path, uid, gid)

Change ownership of a file.

Parameters:

• path string existing file path
• uid string or int new owner user id
• gid string or int new owner group id

Returns:

int 0, if successful

Or

1. nil
2. string error messoge
3. int errnum

See also:

chown(2)

Usage:

local unistd = require "posix.unistd"
-- will fail for a normal user, and print an error
print(unistd.chown ("/etc/passwd", 100, 200))

close (fd)

Close an open file descriptor.

Parameters:

• fd int file descriptor to act on

Returns:

int 0, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

close(2)

Usage:

local unistd = require "posix.unistd"
local ok, errmsg = unistd.close (log)
if not ok then error (errmsg) end

crypt (trypass, salt)

Encrypt a password. Not recommended for general encryption purposes.

Parameters:

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

Returns:

encrypted string

See also:

crypt(3)

Usage:

local pwd = require "posix.pwd"
local unistd = require "posix.unistd"

local salt, hash = pwd.pwent:match ":$6$(.-)$([^:]+)"
if unistd.crypt (trypass, salt) ~= hash then
  error "wrong password"
end

dup (fd)

Duplicate an open file descriptor.

Parameters:

• fd int file descriptor to act on

Returns:

int new file descriptor duplicating fd, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

dup(2)

Usage:

local stdio = require "posix.stdio"
local unistd = require "posix.unistd"

outfd = unistd.dup (stdio.fileno (io.stdout))

dup2 (fd, newfd)

Duplicate one open file descriptor to another. If newfd references an open file already, it is closed before being reallocated to fd.

Parameters:

• fd int an open file descriptor to act on
• newfd int new descriptor to duplicate fd

Returns:

int new file descriptor, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

dup2(2)

exec (path, argt)

Execute a program at exactly path.

Parameters:

• path string
• argt table arguments (table can include index 0)

Returns:

1. nil
2. string error message
3. int errnum

See also:

execve(2)

Usage:

exec ("/bin/bash", {[0] = "-sh", "--norc"})

execp (path, argt)

Execute a program found using command PATH search, like the shell.

Parameters:

• path string
• argt table arguments (table can include index 0)

Returns:

1. nil
2. string error message
3. int errnum

See also:

execve(2)

fdatasync (fd)

Synchronize a file's in-core state with storage device without metadata.

Parameters:

• fd int

Returns:

int 0, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

fdatasync(2)

fork ()

Fork this program.

Returns:

int 0 in the resulting child process

Or

int process id of child, in the calling process

Or

1. nil
2. string error message
3. int errnum

See also:

• fork(2)
• fork.lua
• fork2.lua

Usage:

local unistd = require "posix.unistd"

local pid, errmsg = unistd.fork ()
if pid == nil then
  error (errmsg)
elseif pid == 0 then
  print ("in child:", unistd.getpid "pid")
else
  print (require "posix.sys.wait".wait (pid))
end
os.exit ()

fsync (fd)

Synchronize a file's in-core state with storage device.

Parameters:

• fd int

Returns:

int 0, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

• fsync(2)
• sync

ftruncate (fd, length)

Truncate a file to a specified length.

Parameters:

• fd int the file descriptor to act on
• length int the length to truncate to

Returns:

int 0, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

ftruncate(2)

getcwd ()

Current working directory for this process.

Returns:

string path of current working directory, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

getcwd(3)

getegid ()

Return effective group id of calling process.

Returns:

int effective group id of calling process

See also:

getgid

geteuid ()

Return effective user id of calling process.

Returns:

int effective user id of calling process

See also:

getuid

getgid ()

Return group id of calling process.

Returns:

int group id of calling process

See also:

getegid

getgroups ()

Get list of supplementary group ids.

Returns:

table group id, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

getgroups(2)

gethostid ()

Get host id.

Returns:

int host id, if successful

Or

1. nil
2. string error message

See also:

gethostid(3)

getopt (arg, opts[, opterr=0[, optind=1]])

Parse command-line options.

Parameters:

• arg command line arguments
• opts string short option specifier
• opterr int index of the option with an error (default 0)
• optind int index of the next unprocessed option (default 1)

Returns:

option iterator, returning 3 values

See also:

• getopt(3)
• getopt.lua

Usage:

local getopt = require "posix.getopt".getopt
for opt, opterr, i in getopt (arg, "ho:v", opterr, i) do
  process (arg, opterr, i)
end

getpgrp ()

Return process group id of calling process.

Returns:

int process group id of calling process

See also:

getpid

getpid ()

Return process id of calling process.

Returns:

int process id of calling process

getppid ()

Return parent process id of calling process.

Returns:

int parent process id of calling process

See also:

getpid

getuid ()

Return user id of calling process.

Returns:

int user id of calling process

See also:

geteuid

isatty (fd)

Test whether a file descriptor refers to a terminal.

Parameters:

• fd int file descriptor to act on

Returns:

int 1 if fd is open and refers to a terminal, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

isatty(3)

lchown (path, uid, gid)

This is like chown, but does not dereference symbolic links. In other words, if a file is a symlink, then it changes ownership of the symlink itself.

Parameters:

• path string existing file path
• uid string or int new owner user id
• gid string or int new owner group id

Returns:

int 0, if successful

Or

1. nil
2. string error messoge
3. int errnum

See also:

lchown(2)

Usage:

local unistd = require "posix.unistd"
-- will fail for a normal user, and print an error
print(unistd.lchown ("/etc/passwd", 100, 200))

link (target, link[, soft=false])

Create a link.

Parameters:

• target string name
• link string name
• soft bool link (default false)

Returns:

int 0, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

• link(2)
• symlink(2)

linkat (targetdir, target, linkdir, link, flags)

Create a link at specified directory.

Parameters:

• targetdir int fd
• target string name
• linkdir int fd
• link string name
• flags int

Returns:

int 0, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

linkat(2)

lseek (fd, offset, whence)

reposition read/write file offset

Parameters:

• fd int open file descriptor to act on
• offset int bytes to seek
• whence int one of SEEK_SET, SEEK_CUR or SEEK_END

Returns:

int new offset, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

lseek(2)

nice (inc)

change process priority

Parameters:

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

Returns:

int new nice value, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

nice(2)

pathconf (path, key)

Get a value for a configuration option for a filename.

Parameters:

• path string optional
• key int one of _PC_LINK_MAX, _PC_MAX_CANON, _PC_NAME_MAX, _PC_PIPE_BUF, _PC_CHOWN_RESTRICTED, _PC_NO_TRUNC or _PC_VDISABLE

Returns:

int associated path configuration value

See also:

pathconf(3)

Usage:

local unistd = require "posix.unistd"
for a, b in pairs (unistd.pathconf "/dev/tty") do print(a, b) end

pipe ()

Creates a pipe.

Returns:

1. int read end file descriptor
2. int write end file descriptor, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

• pipe(2)
• fork.lua

read (fd, count)

Read bytes from a file.

Parameters:

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

Returns:

string string from fd with at most count bytes, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

read(2)

readlink (path)

Read value of a symbolic link.

Parameters:

• path string file to act on

Returns:

string link target, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

readlink(2)

rmdir (path)

Remove a directory.

Parameters:

• path string file to act on

Returns:

int 0, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

rmdir(2)

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 int (uid, gid or pid for every value of what except 's')
• gid int (only for what value 'p') (optional)

Returns:

int 0, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

• setuid(2)
• seteuid(2)
• setgid(2)
• setegid(2)
• setsid(2)
• setpgid(2)

sleep (seconds)

Sleep for a number of seconds.

Parameters:

• seconds int minimum numebr of seconds to sleep

Returns:

int 0 if the requested time has elapsed

Or

int unslept seconds remaining, if interrupted

See also:

• sleep(3)
• posix.time.nanosleep

sync ()

Commit buffer cache to disk.

See also:

• fsync
• sync(2)

sysconf (key)

Get configuration information at runtime.

Parameters:

• key int one of _SC_ARG_MAX, _SC_CHILD_MAX, _SC_CLK_TCK, _SC_JOB_CONTROL, _SC_OPEN_MAX, _SC_NGROUPS_MAX, _SC_SAVED_IDS, _SC_STREAM_MAX, _SC_PAGESIZE, _SC_TZNAME_MAX or _SC_VERSION,

Returns:

int associated system configuration value

See also:

sysconf(3)

tcgetpgrp (fd)

Get id of foreground process group of terminal fd.

Parameters:

• fd int the file descriptor of the controlling terminal of the current process

Returns:

int id of foreground process group, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

tcgetpgrp(2)

tcsetpgrp (fd, pgid)

Make process group pgid the foreground process group of terminal fd.

Parameters:

• fd int the file descriptor of the controlling terminal of the current process
• pgid int id of the process group to make foreground process group

Returns:

int 0, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

tcsetpgrp(2)

truncate (path, length)

Truncate a file to a specified length.

Parameters:

• path string file to act on
• length int the length to truncate to

Returns:

int 0, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

ftruncate(2)

ttyname ([fd=0])

Name of a terminal device.

Parameters:

• fd int file descriptor to process (default 0)

Returns:

string name, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

ttyname(3)

unlink (path)

Unlink a file.

Parameters:

• path string

Returns:

int 0, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

unlink(2)

write (fd, buf[, nbytes=#buf[, offset=0]])

Write bytes to a file. If nbytes is nil or omitted, write all bytes from offset through to the end of buf. If offset is nil or omitted, start writing bytes from the beginning of buf. Bounds checks are enforced, returning posix.errno.EINVAL before attempting to write any bytes, if the requested parameters would access bytes outside buf.

Parameters:

• fd int the file descriptor to act on
• buf string containing bytes to write
• nbytes int number of bytes to write (default #buf)
• offset int skip the first offset bytes of buf (default 0)

Returns:

int number of bytes written, if successful

Or

1. nil
2. string error message
3. int errnum

See also:

write(2)

Constants

posix.unistd

Standard constants. Any constants not available in the underlying system will be nil valued.

Fields:

• _PC_CHOWN_RESTRICTED int return 1 if chown requires appropriate privileges, 0 otherwise
• _PC_LINK_MAX int maximum file link count
• _PC_MAX_CANON int maximum bytes in terminal canonical input line
• _PC_MAX_INPUT int maximum number of bytes in a terminal input queue
• _PC_NAME_MAX int maximum number of bytes in a file name
• _PC_NO_TRUNC int return 1 if over-long file names are truncated
• _PC_PATH_MAXmaximum int number of bytes in a pathname
• _PC_PIPE_BUF int maximum number of bytes in an atomic pipe write
• _PC_VDISABLE int terminal character disabling value
• _SC_ARG_MAX int maximum bytes of argument to posix.unistd.execp
• _SC_CHILD_MAX int maximum number of processes per user
• _SC_CLK_TCK int statistics clock frequency
• _SC_JOB_CONTROL int return 1 if system has job control, -1 otherwise
• _SC_NGROUPS_MAX int maximum number of supplemental groups
• _SC_OPEN_MAX int maximum number of open files per user
• _SC_SAVED_IDS int return 1 if system supports saved user and group ids, -1 otherwise
• _SC_STREAM_MAX int maximum number of streams per process
• _SC_TZNAME_MAX int maximum number of timezone types
• _SC_VERSION int POSIX.1 compliance version
• SEEK_CUR int relative file pointer position
• SEEK_END int set file pointer to the end of file
• SEEK_SET int absolute file pointer position
• STDERR_FILENO int standard error file descriptor
• STDIN_FILENO int standard input file descriptor
• STDOUT_FILENO int standard output file descriptor

Usage:

-- Print unistd constants supported on this host.
for name, value in pairs (require "posix.unistd") do
  if type (value) == "number" then
    print (name, value)
   end
end