# 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

generated by LDoc 1.5.0 Last updated 2025-02-16 13:16:41