# Module `posix`

Lua POSIX bindings.

In addition to the convenience functions documented in this module, many APIs from submodules are copied into the return table for backwards compatibility and, if necessary, wrapped to match the deprecated API.

This means that your old code will continue to work, but that you can use the improved documented APIs in new code.

## Functions

chmod (path, mode) | Change the mode of the path.
creat (path, mode) | Create a file.
euidaccess (file, mode) | Check permissions like posix.unistd.access, but for euid.
execx (task, ...) | Exec a command or Lua function.
glob (args) | Find all files in this directory matching a shell pattern.
mkdir (path) | Make a directory.
mkfifo (path) | Make a FIFO pipe.
msgget (key[, flags=0[, mode='rw-rw-rw-']]) | Get a message queue identifier
open (path, oflags, modestr) | Open a file.
openpty () | Open a pseudo-terminal.
pclose (pfd) | Close a pipeline opened with popen or popen_pipeline.
popen (task, mode[, pipe_fn]) | Run a command or Lua function in a sub-process.
popen_pipeline (t, mode[, pipe_fn]) | Perform a series of commands and Lua functions as a pipeline.
setlogmask (...) | Set log priority mask
spawn (task, ...) | Run a command or function in a sub-process using posix.execx.
timeradd (x, y) | Add one gettimeofday() returned timeval to another.
timercmp (x, y) | Compare one gettimeofday() returned timeval with another
timersub (x, y) | Subtract one gettimeofday() returned timeval from another.
umask ([mode]) | Set file mode creation mask.

## Metamethods

__index (name) | Preloading of luaposix modules.

## Functions

chmod (path, mode)
  Change the mode of the path.

  ### Parameters:

  - path string existing file path
  - mode string

    one of the following formats:

        * 'rwxrwxrwx' (e.g. 'rw-rw-r--')
        * 'ugo+-=rwx' (e.g. 'u+w')
        * '+-=rwx'    (e.g. '+w')

  ### Returns:

  int `0`, if successful

  ### Or

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

  ### See also:

  chmod(2)

  ### Usage:

      chmod('bin/dof', '+x')

creat (path, mode)
  Create a file. This function is obsoleted by posix.fcntl.open with `posix.O_CREAT`.

  ### Parameters:

  - path string name of file to create
  - mode string permissions with which to create file

  ### Returns:

  int file descriptor of file at path, if successful

  ### Or

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

  ### See also:

  - creat(2)
  - posix.chmod

  ### Usage:

      fd = creat('data', 'rw-r-----')

euidaccess (file, mode)
  Check permissions like posix.unistd.access, but for euid. Based on the glibc function of the same name. Does not always check for read-only file system, text busy, etc., and does not work with ACLs &c.

  ### Parameters:

  - file string file to check
  - mode string checks to perform (as for access)

  ### Returns:

  int `0`, if access allowed

  ### Or

  nil (and errno is set)
execx (task, ...)
  Exec a command or Lua function.

  ### Parameters:

  - task table or function argument list for posix.unistd.execp or a Lua function, which should read from standard input, write to standard output, and return an exit code
  - ... positional arguments to the function

  ### Returns:

  1. nil on error (normally does not return)
  2. string error message
glob (args)
  Find all files in this directory matching a shell pattern. The flag MARK appends a trailing slash to matches that are directories.

  ### Parameters:

  - args table, string or nil the three possible parameters can be used to override the default values for `pattern` and `MARK`, which are `"*"` and `false` respectively. A table will be checked for optional keys `pattern` and `MARK`. A string will be used as the glob pattern.

  ### Returns:

  table matching files and directories, if successful

  ### Or

  1. nil
  2. one of `GLOB_BORTED`, `GLOB_NOMATCH` or `GLOB_NOSPACE`

  ### See also:

  posix.glob.glob
mkdir (path)
  Make a directory.

  ### Parameters:

  - path string location in file system to create directory

  ### Returns:

  int `0`, if successful

  ### Or

  1. nil
  2. string error message
  3. int errnum
mkfifo (path)
  Make a FIFO pipe.

  ### Parameters:

  - path string location in file system to create fifo

  ### Returns:

  int `0`, if successful

  ### Or

  1. nil
  2. string error message
  3. int errnum
msgget (key[, flags=0[, mode='rw-rw-rw-']])
  Get a message queue identifier

  ### Parameters:

  - key int message queue id, or `IPC_PRIVATE` for a new queue
  - flags int bitwise OR of zero or more from `IPC_CREAT` and `IPC_EXCL` (default 0)
  - mode string execute bits are ignored (default 'rw-rw-rw-')

  ### Returns:

  int message queue identifier, if successful

  ### Or

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

  ### See also:

  msgget(2)
open (path, oflags, modestr)
  Open a file.

  ### Parameters:

  - path string file to act on
  - oflags int bitwise OR of zero or more of `O_RDONLY`, `O_WRONLY`, `O_RDWR`, `O_APPEND`, `O_CREAT`, `O_DSYNC`, `O_EXCL`, `O_NOCTTY`, `O_NONBLOCK`, `O_RSYNC`, `O_SYNC`, `O_TRUNC`
  - modestr string (used with `O_CREAT`; see chmod for format)

  ### Returns:

  int file descriptor for path, if successful

  ### Or

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

  ### See also:

  open(2)

  ### Usage:

      fd = posix.open('data', bit.bor(posix.O_CREAT, posix.O_RDWR), 'rw-r-----')

openpty ()
  Open a pseudo-terminal. Based on the glibc function of the same name.

  ### Returns:

  1. int master file descriptor
  2. int slave file descriptor
  3. string slave file name, if successful

  ### Or

  1. nil
  2. string error message
  3. int errnum
pclose (pfd)
  Close a pipeline opened with popen or popen_pipeline.

  ### Parameters:

  - pfd table pipeline object

  ### Returns:

  values as for posix.sys.wait.wait, for the last (or only) stage of the pipeline
popen (task, mode[, pipe_fn])
  Run a command or Lua function in a sub-process.

  ### Parameters:

  - task table argument list for posix.unistd.execp or a Lua function, which should read from standard input, write to standard output, and return an exit code
  - mode string `"r"` for read or `"w"` for write
  - pipe_fn function function returning a paired read and write file descriptor (default posix.unistd.pipe) (optional)

  ### Returns:

  pfd pipeline object

  ### See also:

  - posix.execx
  - posix.spawn
popen_pipeline (t, mode[, pipe_fn])
  Perform a series of commands and Lua functions as a pipeline.

  ### Parameters:

  - t table tasks for posix.execx
  - mode string `"r"` for read or `"w"` for write
  - pipe_fn function function returning a paired read and write file descriptor (default posix.unistd.pipe) (optional)

  ### Returns:

  pfd pipeline object
setlogmask (...)
  Set log priority mask

  ### Parameters:

  - ... int zero or more of `LOG_EMERG`, `LOG_ALERT`, `LOG_CRIT`, `LOG_WARNING`, `LOG_NOTICE`, `LOG_INFO` and `LOG_DEBUG`

  ### Returns:

  int `0`, if successful

  ### Or

  1. nil
  2. string error message
  3. int errnum
spawn (task, ...)
  Run a command or function in a sub-process using posix.execx.

  ### Parameters:

  - task table argument list for posix.unistd.execp or a Lua function, which should read from standard input, write to standard output, and return an exit code
  - ... as for posix.execx

  ### Returns:

  1. int exit status, or signal number responsible for "killed" or "stopped"
  2. string "exited", "killed" or "stopped"

  ### Or

  1. int errnum
  2. string error message
timeradd (x, y)
  Add one gettimeofday() returned timeval to another.

  ### Parameters:

  - x a timeval
  - y another timeval

  ### Returns:

  x + y, adjusted for usec overflow
timercmp (x, y)
  Compare one gettimeofday() returned timeval with another

  ### Parameters:

  - x a timeval
  - y another timeval

  ### Returns:

  0 if x and y are equal, >0 if x is newer, <0 if y is newer
timersub (x, y)
  Subtract one gettimeofday() returned timeval from another.

  ### Parameters:

  - x a timeval
  - y another tiimeval

  ### Returns:

  x - y, adjusted for usec underflow
umask ([mode])
  Set file mode creation mask.

  ### Parameters:

  - mode string file creation mask string (optional)

  ### Returns:

  string previous umask

  ### See also:

  - umask(2)
  - posix.sys.stat.umask

## Metamethods

__index (name)
  Preloading of luaposix modules. Submodule tables are also preloaded into this top-level module, where they can be accessed without requiring them separately.

  ### Parameters:

  - name string submodule name

  ### Returns:

  table or nil the submodule that was preloaded to satisfy `name`, otherwise `nil` if no such submodule is available.

  ### Usage:

      local version = require 'posix'.version

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