lsh

• Index

Contents

• Functions
• Child methods
• Output

Modules

• lsh
• lsh.cmd
• lsh.cmd.child
• lsh.cmd.status
• lsh.fio
• lsh.fio.fh
• lsh.memfd
• lsh.path
• lsh.pipeline
• lsh.pipeline.children
• lsh.pipeline.pstatus
• lsh.stringx
• lsh.time

Topics

• README

Examples

• cmd_spec.lua
• helper.lua
• libc_spec.lua
• memfd_spec.lua
• nofile_spec.lua
• path_spec.lua
• pipeline_spec.lua
• stringx_spec.lua

Module lsh.cmd.child

Representation of a running or exited child process.

Use this module to manage child processes. A lsh.cmd instance holds the configuration of the process and spawns the child.

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 a new child instance and runs the program defined in cmd.

Child methods

type ()	Returns the instance type.
kill (self[, signal])	Sends a signal to the child process.
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)	Waits for the child to exit and returns an output struct with the stdout and stderr handles of the child.

Output

output

The output of a finished process.

Functions

new (cmd[, clone])

Constructs a new child instance and runs the program defined in cmd.

You do not need to call this function directly. Use cmd.run or cmd.spawn.

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'

local child = require 'lsh.cmd.child'

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'):spawn():type() == 'child')

kill (self[, signal])

Sends a signal to the child process.

If you do not give a signal, it sends SIGKILL (kill), which forces the child process to exit.

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.

After the first call, this function always returns the same value.

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 does not block the calling thread. It only checks if the child process exited.

If the child exited, it reaps the process ID and returns status. Later calls return the same status. If the exit status is not available yet, it returns false.

Parameters:

• self lsh.cmd.child

Returns:

lsh.cmd.status status struct

Or

false

Or

1. nil
2. string error message

Usage:

local sh = require 'lsh'

local child = sh.cmd('ls'):spawn()
child:try_wait()

wait_with_output (self)

Waits for the child to exit and returns an output struct with the stdout and stderr handles of the child.

By default, stdin, stdout and stderr are inherited from the parent. To capture the output in output, set a memfd instance with stdout(sh.memfd()) or stderr(sh.memfd()).

Parameters:

• self lsh.cmd.child

Returns:

lsh.cmd.child.output output struct

Or

1. nil
2. string error message

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.

The cmd.output method and the wait_with_output method of a child process return this table.

Fields:

• stdout stdout of cmd instance (if any)
• stderr stderr of cmd instance (if any)
• status status struct