luaposix 33.2.1

• Index

Contents

• Functions
• Constants

Modules

• posix
• posix.bit32
• posix.ctype
• posix.curses
• posix.dirent
• posix.errno
• posix.fcntl
• posix.fnmatch
• posix.getopt
• 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

Classes

• posix.curses.chstr
• posix.curses.window

Examples

• curses.lua
• dir.lua
• fork.lua
• fork2.lua
• getopt.lua
• glob.lua
• limit.lua
• lock.lua
• netlink-uevent.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.
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 without using the shell.
execp (path, argt)	Execute a program using 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.
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.
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.
link (target, link[, soft=false])	Create a link.
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.
ttyname ([fd=0])	Name of a terminal device.
unlink (path)	Unlink a file.
write (fd, buf)	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:

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

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:

status, errstr, errno = P.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:

-- will fail for a normal user, and print an error
print(P.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 ok, errmsg = P.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 salt, hash = pwent:match ":$6$(.-)$([^:]+)"
if P.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 outfd = P.dup (P.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 without using the shell.

Parameters:

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

Returns:

1. nil
2. string error message

See also:

execve(2)

Usage:

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

execp (path, argt)

Execute a program using the shell.

Parameters:

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

Returns:

1. nil
2. string error message

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 pid, errmsg = P.fork ()
if pid == nil then
  error (errmsg)
elseif pid == 0 then
  print ("in child:", P.getpid "pid")
else
  print (P.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

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

See also:

getgroups(2)

gethostid ()

Get host id.

Returns:

int host id

Or

1. nil
2. string error message

See also:

gethostid(3)

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)

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)

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:

for a, b in pairs (P.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

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_TZNAME_MAX or _SC_VERSION,

Returns:

int associated system configuration value

See also:

sysconf(3)

ttyname ([fd=0])

Name of a terminal device.

Parameters:

• fd int file descriptor to process (default 0)

Returns:

string name

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)

Write bytes to a file.

Parameters:

• fd int the file descriptor to act on
• buf string containing bytes to write

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