Skip to main content

process

Functionality that allows you to launch subprocesses and read or write to them in a non-blocking fashion.

ERROR_INVAL​

(field) ERROR_INVAL: integer

Error triggered when trying to terminate or kill a non running process, its value is platform dependent, so the value declared on this interface does not represents the real one.

ERROR_NOMEM​

(field) ERROR_NOMEM: integer

Error triggered when no memory is available to allocate the process, its value is platform dependent, so the value declared on this interface does not represents the real one.

ERROR_PIPE​

(field) ERROR_PIPE: integer

Error triggered when the stdout, stderr or stdin fails while reading or writing, its value is platform dependent, so the value declared on this interface does not represents the real one.

ERROR_TIMEDOUT​

(field) ERROR_TIMEDOUT: integer

Error triggered when a process takes more time than that specified by the deadline parameter given on process:start(), its value is platform dependent, so the value declared on this interface does not represents the real one.

ERROR_WOULDBLOCK​

(field) ERROR_WOULDBLOCK: integer

Error triggered when a read or write action is blocking, its value is platform dependent, so the value declared on this interface does not represents the real one.

REDIRECT_DEFAULT​

(field) REDIRECT_DEFAULT: integer

Default behavior for redirecting streams. This flag is deprecated and for backwards compatibility with reproc only. The behavior of this flag may change in future versions of Pragtical.

REDIRECT_DISCARD​

(field) REDIRECT_DISCARD: integer

Discard this stream (piping it to /dev/null)

REDIRECT_PARENT​

(field) REDIRECT_PARENT: integer

Redirect this stream to the parent.

REDIRECT_PIPE​

(field) REDIRECT_PIPE: integer

Allow Process API to read this stream via process:read functions.

REDIRECT_STDOUT​

(field) REDIRECT_STDOUT: integer

Redirect this stream to stdout. This flag can only be used on process.options.stderr.

STREAM_STDERR​

(field) STREAM_STDERR: integer

Used for the process:close_stream() method to close stderr.

STREAM_STDIN​

(field) STREAM_STDIN: integer

Used for the process:close_stream() method to close stdin.

STREAM_STDOUT​

(field) STREAM_STDOUT: integer

Used for the process:close_stream() method to close stdout.

WAIT_DEADLINE​

(field) WAIT_DEADLINE: integer

Instruct process:wait() to wait until the deadline given on process:start()

WAIT_INFINITE​

(field) WAIT_INFINITE: integer

Instruct process:wait() to wait until the process ends.

process.options​

Options that can be passed to process.start()

cwd​

(field) cwd: string

env​

(field) env: table<string, string>

stderr​

(field) stderr: `process.REDIRECT_DEFAULT`|`process.REDIRECT_DISCARD`|`process.REDIRECT_PARENT`|`process.REDIRECT_PIPE`|`process.REDIRECT_STDOUT`

stdin​

(field) stdin: `process.REDIRECT_DEFAULT`|`process.REDIRECT_DISCARD`|`process.REDIRECT_PARENT`|`process.REDIRECT_PIPE`|`process.REDIRECT_STDOUT`

stdout​

(field) stdout: `process.REDIRECT_DEFAULT`|`process.REDIRECT_DISCARD`|`process.REDIRECT_PARENT`|`process.REDIRECT_PIPE`|`process.REDIRECT_STDOUT`

timeout​

(field) timeout: number

start​

function process.start(command_and_params: table, options: process.options)
  -> process|nil
  2. errmsg: string
  3. errcode: integer|`process.ERROR_INVAL`|`process.ERROR_NOMEM`|`process.ERROR_PIPE`|`process.ERROR_TIMEDOUT`...(+1)

Create and start a new process

@param command_and_params — First index is the command to execute

and subsequente elements are parameters for the command.

errcode:
    | `process.ERROR_PIPE`
    | `process.ERROR_WOULDBLOCK`
    | `process.ERROR_TIMEDOUT`
    | `process.ERROR_INVAL`
    | `process.ERROR_NOMEM`

strerror​

function process.strerror(code: integer)
  -> string|nil

Translates an error code into a useful text message

close_stream​

(method) process:close_stream(stream: `process.STREAM_STDERR`|`process.STREAM_STDIN`|`process.STREAM_STDOUT`)
  -> integer|nil
  2. errmsg: string
  3. errcode: integer|`process.ERROR_INVAL`|`process.ERROR_NOMEM`|`process.ERROR_PIPE`|`process.ERROR_TIMEDOUT`...(+1)

Allows you to close a stream pipe that you will not be using.

stream:
    | `process.STREAM_STDIN`
    | `process.STREAM_STDOUT`
    | `process.STREAM_STDERR`

errcode:
    | `process.ERROR_PIPE`
    | `process.ERROR_WOULDBLOCK`
    | `process.ERROR_TIMEDOUT`
    | `process.ERROR_INVAL`
    | `process.ERROR_NOMEM`

kill​

(method) process:kill()
  -> boolean|nil
  2. errmsg: string
  3. errcode: integer|`process.ERROR_INVAL`|`process.ERROR_NOMEM`|`process.ERROR_PIPE`|`process.ERROR_TIMEDOUT`...(+1)

Sends SIGKILL to the process

errcode:
    | `process.ERROR_PIPE`
    | `process.ERROR_WOULDBLOCK`
    | `process.ERROR_TIMEDOUT`
    | `process.ERROR_INVAL`
    | `process.ERROR_NOMEM`

pid​

(method) process:pid()
  -> id: integer

Get the process id.

@return id — Process id or 0 if not running.

read​

(method) process:read(stream: `process.STREAM_STDERR`|`process.STREAM_STDIN`|`process.STREAM_STDOUT`, len?: integer)
  -> string|nil
  2. errmsg: string
  3. errcode: integer|`process.ERROR_INVAL`|`process.ERROR_NOMEM`|`process.ERROR_PIPE`|`process.ERROR_TIMEDOUT`...(+1)

Read from the given stream type, if the process fails with a ERROR_PIPE it is automatically destroyed returning nil along error message and code.

@param len — Amount of bytes to read, defaults to 2048.

stream:
    | `process.STREAM_STDIN`
    | `process.STREAM_STDOUT`
    | `process.STREAM_STDERR`

errcode:
    | `process.ERROR_PIPE`
    | `process.ERROR_WOULDBLOCK`
    | `process.ERROR_TIMEDOUT`
    | `process.ERROR_INVAL`
    | `process.ERROR_NOMEM`

read_stderr​

(method) process:read_stderr(len?: integer)
  -> string|nil
  2. errmsg: string
  3. errcode: integer|`process.ERROR_INVAL`|`process.ERROR_NOMEM`|`process.ERROR_PIPE`|`process.ERROR_TIMEDOUT`...(+1)

Read from stderr, if the process fails with a ERROR_PIPE it is automatically destroyed returning nil along error message and code.

@param len — Amount of bytes to read, defaults to 2048.

errcode:
    | `process.ERROR_PIPE`
    | `process.ERROR_WOULDBLOCK`
    | `process.ERROR_TIMEDOUT`
    | `process.ERROR_INVAL`
    | `process.ERROR_NOMEM`

read_stdout​

(method) process:read_stdout(len?: integer)
  -> string|nil
  2. errmsg: string
  3. errcode: integer|`process.ERROR_INVAL`|`process.ERROR_NOMEM`|`process.ERROR_PIPE`|`process.ERROR_TIMEDOUT`...(+1)

Read from stdout, if the process fails with a ERROR_PIPE it is automatically destroyed returning nil along error message and code.

@param len — Amount of bytes to read, defaults to 2048.

errcode:
    | `process.ERROR_PIPE`
    | `process.ERROR_WOULDBLOCK`
    | `process.ERROR_TIMEDOUT`
    | `process.ERROR_INVAL`
    | `process.ERROR_NOMEM`

returncode​

(method) process:returncode()
  -> number|nil

Get the exit code of the process or nil if still running.

running​

(method) process:running()
  -> boolean

Check if the process is running

terminate​

(method) process:terminate()
  -> boolean|nil
  2. errmsg: string
  3. errcode: integer|`process.ERROR_INVAL`|`process.ERROR_NOMEM`|`process.ERROR_PIPE`|`process.ERROR_TIMEDOUT`...(+1)

Sends SIGTERM to the process

errcode:
    | `process.ERROR_PIPE`
    | `process.ERROR_WOULDBLOCK`
    | `process.ERROR_TIMEDOUT`
    | `process.ERROR_INVAL`
    | `process.ERROR_NOMEM`

wait​

(method) process:wait(timeout: integer|`process.WAIT_DEADLINE`|`process.WAIT_INFINITE`)
  -> exit_status: integer|nil
  2. errmsg: string
  3. errcode: integer|`process.ERROR_INVAL`|`process.ERROR_NOMEM`|`process.ERROR_PIPE`|`process.ERROR_TIMEDOUT`...(+1)

Wait the specified amount of time for the process to exit.

@param timeout — Time to wait in milliseconds,

if 0, the function will only check if process is running without waiting.

@return exit_status — The process exit status or nil on error

@return errmsg

@return errcode

timeout:
    | `process.WAIT_INFINITE`
    | `process.WAIT_DEADLINE`

errcode:
    | `process.ERROR_PIPE`
    | `process.ERROR_WOULDBLOCK`
    | `process.ERROR_TIMEDOUT`
    | `process.ERROR_INVAL`
    | `process.ERROR_NOMEM`

write​

(method) process:write(data: string)
  -> bytes: integer|nil
  2. errmsg: string
  3. errcode: integer|`process.ERROR_INVAL`|`process.ERROR_NOMEM`|`process.ERROR_PIPE`|`process.ERROR_TIMEDOUT`...(+1)

Write to the stdin, if the process fails with a ERROR_PIPE it is automatically destroyed returning nil along error message and code.

@return bytes — The amount of bytes written or nil if error

@return errmsg

@return errcode

errcode:
    | `process.ERROR_PIPE`
    | `process.ERROR_WOULDBLOCK`
    | `process.ERROR_TIMEDOUT`
    | `process.ERROR_INVAL`
    | `process.ERROR_NOMEM`