Module lsh.cmd.child

Representation of a running or exited child process.

This module is used to represent and manage child processes. A child process is created via the lsh.cmd instance, which configures the spawning process and can itself be constructed using a builder-style interface.

Example

local sh = require 'lsh'

local child, err = sh.cmd('cat'):arg('file.txt')
                                :spawn()
if err then error('failed to execute child') end

local ecode, err = child:wait()
if err then error('failed to wait on child') end

assert(ecode:success())

Functions

new (cmd[, clone]) Constructs the new child handle instance from program defined in cmd and executes it.

Child methods

type () Returns the instance type.
kill (self[, signal]) Sends a child process a signal.
id (self) Returns the OS-assigned process identifier associated with this child.
wait (self) Waits for the child to exit completely, returning the status that it exited with.
try_wait (self) Attempts to collect the exit status of the child if it has already exited.
wait_with_output (self) Simultaneously waits for the child to exit and collect all remaining output on the stdout/stderr handles, returning an output struct.

Output

output The output of a finished process.


Functions

new (cmd[, clone])
Constructs the new child handle instance from program defined in cmd and executes it.

There is no need to use this method directly, see cmd.run and cmd.spawn for practical program execution.

Parameters:

  • cmd lsh.cmd
  • clone boolean control cloning of input cmd (true by default) (optional)

Returns:

    lsh.cmd.child new child instance

Usage:

    local sh = require 'lsh'

sh.cmd.child.new(sh.cmd('echo', 1))

Child methods

type ()
Returns the instance type.

Returns:

    the string "child"

Usage:

    local sh = require 'lsh'

assert(sh.cmd('ls'):run().type() == 'child')
kill (self[, signal])
Sends a child process a signal.

By default forces the child process to exit by sending SIGKILL (kill).

Valid signals: hup int quit ill trap abrt bus fpe kill usr1 segv usr2 pipe alrm term stkflt chld cont stop tstp ttin ttou urg xcpu xfsz vtalrm prof winch io pwr sys

Parameters:

  • self lsh.cmd.child
  • signal string signal name (optional)

Returns:

    boolean true

Or

  1. nil
  2. string error message

Usage:

    local sh = require 'lsh'

local child = sh.cmd('sleep', 10):spawn()
child:kill()
id (self)
Returns the OS-assigned process identifier associated with this child.

Parameters:

  • self lsh.cmd.child

Returns:

    number process identifier

Usage:

    local sh = require 'lsh'

local child = sh.cmd('ls'):spawn()
child:id()
wait (self)
Waits for the child to exit completely, returning the status that it exited with.

This function will continue to have the same return value after it has been called at least once.

Parameters:

  • self lsh.cmd.child

Returns:

    lsh.cmd.status status struct

Usage:

    local sh = require 'lsh'

local child = sh.cmd('ls'):spawn()
child:wait()
try_wait (self)
Attempts to collect the exit status of the child if it has already exited.

This function will not block the calling thread and will only check to see if the child process has exited or not. If the child has exited then process ID is reaped. This function is guaranteed to repeatedly return a successful exit status so long as the child has already exited.

If the child has exited, then status is returned. If the exit status is not available at this time then false is returned.

Parameters:

  • self lsh.cmd.child

Returns:

    lsh.cmd.status status struct

Or

    false

Or

  1. nil
  2. err

Usage:

    local sh = require 'lsh'

local child = sh.cmd('ls'):spawn()
child:try_wait()
wait_with_output (self)
Simultaneously waits for the child to exit and collect all remaining output on the stdout/stderr handles, returning an output struct.

By default, stdin, stdout and stderr are inherited from the parent. In order to capture the output into output it is necessary to create new memfd instances between parent and child. Use stdout(sh.memfd()) or stderr(sh.memfd()), respectively.

Parameters:

  • self lsh.cmd.child

Returns:

    lsh.cmd.child.output output struct

Or

  1. nil
  2. err

Usage:

    local sh = require 'lsh'

local child, err = sh.cmd('cat'):arg('file.txt')
                                :stdout(sh.memfd())
                                :spawn()
if not child then error(err) end

local output, err = child:wait_with_output()
if not output then error(err) end
assert(output.status:success())
-- read output line by line
for line in output.stdout:lines() do
  print(line)
end

Output

output
The output of a finished process.

This is returned by either the cmd.output method, or the wait_with_output method of a child process.

Fields:

  • stdout stdout of cmd instance (if any)
  • stderr stderr of cmd instance (if any)
  • status status struct
generated by LDoc 1.4.6 Last updated 1980-01-01 00:00:00