# Module `posix`

Lua POSIX bindings.

In addition to the convenience functions documented in this module, all APIs from submodules are copied into the return table for convenience and backwards compatibility.

## 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.
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.
pclose (pfd) | Close a pipeline opened with popen or popen_pipeline.
popen (as, mode[, pipe_fn]) | Run a commands 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 `P.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.

## 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:

      P.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 = P.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:

  0 if access allowed; `nil` otherwise (and errno is set)
execx (task, ...)
  Exec a command or Lua function.

  ### Parameters:

  - task , a table of arguments to `P.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
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 = P.open ("data", bit.bor (P.O_CREAT, P.O_RDWR), "rw-r-----")

pclose (pfd)
  Close a pipeline opened with popen or popen_pipeline.

  ### Parameters:

  - pfd table pipeline object

  ### Returns:

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

  ### Parameters:

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

  ### Returns:

  pfd pipeline object
popen_pipeline (t, mode[, pipe_fn])
  Perform a series of commands and Lua functions as a pipeline.

  ### Parameters:

  - t table tasks for execx
  - mode string `"r"` for read or `"w"` for write
  - pipe_fn func 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 `P.execx`.

  ### Parameters:

  - task , as for `P.execx`.
  - ... as for `P.execx`

  ### Returns:

  values as for `P.wait`
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 timeval

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

generated by LDoc 1.4.3 Last updated 2016-02-27 14:10:34