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:

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:

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:

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:

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:

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:

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

Parameters:

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:

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:

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 2023-06-16 20:19:12