Module eco.sys

System and process related utilities.

Functions

exec (cmd[, env]) Execute a program.
sh (cmd[, timeout=30]) Execute a shell command and return stdout and stderr.
spawn (f) Spawn a new process to run a Lua function.
signal (signum, cb, Additional) Listen for a specific signal and invoke a callback asynchronously.
uptime () Get system uptime.
waitpid (pid) Wait for a child process status change (non-blocking).
getpid () Get current process id.
getppid () Get parent process id.
getpwnam (name) Lookup a user by name.
kill (pid, sig) Send a signal to a process.
fork () Fork the current process.
prctl (option[, arg]) Process control operations.
get_nprocs () Get number of available processors.
strerror (errno) Convert errno value to message.

Fields

SIGINT Signal number for interrupt from keyboard.
SIGTERM Signal number for termination.
SIGHUP Signal number for terminal line hangup.

Class process

process:close () Close stdout and stderr file descriptors.
process:wait ([timeout]) Wait for the process to exit.
process:signal (sig) Send a signal to the process.
process:kill () Force kill the process with SIGKILL.
process:stop ([timeout=3]) Stop the process gracefully, then force kill if needed.
process:read_stdout () Read from process stdout.
process:read_stderr () Read from process stderr.

Class signal

signal:close () Stop listening for the signal and release resources.


Functions

exec (cmd[, env])
Execute a program.

Spawns a new process and returns a process handle object. The returned object provides methods to wait for process exit, read stdout/stderr.

There are two supported calling forms:

  1. Argument list form:

    p, err = sys.exec(cmd, arg1, arg2, ...)

  2. Table form with optional environment:

    p, err = sys.exec({ cmd, arg1, arg2, ... }, env)

In the second form, env is a table of environment variables.

Parameters:

  • cmd string or table
    • a string representing the program to execute, followed by arguments
    • or a table { cmd, arg1, arg2, ... }
  • env table Environment variables table (only valid when first argument is a table form). (optional)

Returns:

    process Process handle object on success.

Or

  1. nil On failure.
  2. string Error message when failed.

Usage:

    -- simple form
local p, err = sys.exec('ls', '-l', '/tmp')
if not p then
    print(err)
end

-- table form with environment
local p, err = sys.exec({ 'printenv', 'A' }, { A = '123' })
sh (cmd[, timeout=30])
Execute a shell command and return stdout and stderr.

This is a convenience wrapper around exec. It accepts a command string or a table of arguments. If a string is provided, it will be executed using /bin/sh -c.

Parameters:

  • cmd string or table

    Command to execute.

    • If string, executed via /bin/sh -c.
    • If table, first element is program, remaining are arguments.
  • timeout number Timeout in seconds for reading stdout/stderr. (default 30)

Returns:

  1. string Standard output of the command.
  2. string Standard error of the command.

Or

  1. nil On failure.
  2. string Error message when failed.

Usage:

    local out, err = sys.sh({ 'echo', 'hello' })
if not out then
    print("Command failed:", e)
else
    print("stdout:", out)
    print("stderr:", err)
end

-- Table form with program and arguments
local out, err, e = sys.sh({ "ls", "-l", "/tmp" })
spawn (f)
Spawn a new process to run a Lua function.

This function forks a child process and runs the given function f inside it. The child process will be terminated if the parent dies (PR_SET_PDEATHSIG = SIGKILL).

Parameters:

  • f function Lua function to run in the child process.

Returns:

    int Child process ID (in the parent process).

Or

  1. nil On failure.
  2. string Error message.

Usage:

    local pid, err = sys.spawn(function()
    print("Hello from child process!")
end)
if not pid then
    print("Failed to spawn child:", err)
else
    print("Spawned child PID:", pid)
end
signal (signum, cb, Additional)
Listen for a specific signal and invoke a callback asynchronously.

This function wraps signalfd and spawns a coroutine to continuously read the signal. When the specified signal sig is received, the callback cb is invoked with any additional arguments.

The returned signal object controls the listener lifetime. Call sig:close() to stop listening.

Internally this function blocks signum in the process mask and uses signalfd for delivery. The signal will be unblocked when the listener is closed.

Note: SIGCHLD is reserved by eco's scheduler for child process reaping and must not be listened to via this API.

Parameters:

  • signum int Signal number to listen for (e.g., sys.SIGINT).
  • cb function Callback function to invoke when the signal occurs.
  • Additional ... arguments passed to the callback.

Returns:

    signal Signal object (use signal:close to stop listening).

Or

  1. nil On failure.
  2. string Error message.

Usage:

    local sig
sig, err = sys.signal(sys.SIGINT, function()
    print('Received SIGINT!')
    sig:close()
end)
if not sig then
    print('Failed to listen for signal:', err)
end
uptime ()
Get system uptime.

Returns:

    int Uptime in seconds.
waitpid (pid)
Wait for a child process status change (non-blocking).

This is a thin wrapper around waitpid(pid, ..., WNOHANG | WUNTRACED).

Parameters:

  • pid int Process id to wait for. Use -1 for any child.

Returns:

  1. int pid The pid that changed state, or 0 if none.
  2. table Status information.

Or

  1. nil On error.
  2. string err Error message.
getpid ()
Get current process id.

Returns:

    int pid
getppid ()
Get parent process id.

Returns:

    int pid
getpwnam (name)
Lookup a user by name.

Parameters:

Returns:

    table User info table with fields: username, password, uid, gid, home, shell.

Or

  1. nil On error or not found.
  2. string err Error message.
kill (pid, sig)
Send a signal to a process.

Parameters:

  • pid int Target pid.
  • sig int Signal number.

Returns:

    boolean true on Success

Or

  1. nil On error
  2. string err Error message.
fork ()
Fork the current process.

Returns:

    int Child pid in parent, 0 in child.

Or

  1. nil On error.
  2. string Error message.
prctl (option[, arg])
Process control operations.

Currently supports PR_SET_PDEATHSIG.

Parameters:

  • option int prctl option.
  • arg int Option-specific argument. (optional)

Returns:

    boolean true on success.

Or

  1. nil On error or unsupported option.
  2. string Error message.
get_nprocs ()
Get number of available processors.

Returns:

    int n
strerror (errno)
Convert errno value to message.

Parameters:

  • errno int Error number.

Returns:

    string message

Fields

SIGINT
Signal number for interrupt from keyboard.
SIGTERM
Signal number for termination.
SIGHUP
Signal number for terminal line hangup.

Class process

Process handle returned by sys.exec.

This object represents a running child process.

process:close ()
Close stdout and stderr file descriptors.
process:wait ([timeout])
Wait for the process to exit.

If the child has already exited before calling this method, it returns immediately with the status cached on this process handle.

Parameters:

  • timeout number Timeout in seconds. (optional)

Returns:

  1. int pid Process id.
  2. int status Exit status.

Or

  1. nil On timeout or error.
  2. string Error message.
process:signal (sig)
Send a signal to the process.

Parameters:

  • sig int Signal number.

Returns:

    boolean true On success.

Or

  1. nil On failure.
  2. string Error message.
process:kill ()
Force kill the process with SIGKILL.

Returns:

    boolean true On success.

Or

  1. nil On failure.
  2. string Error message.
process:stop ([timeout=3])
Stop the process gracefully, then force kill if needed.

This sends SIGTERM first, waits up to timeout seconds, then sends SIGKILL if the process is still alive. Waiting remains coroutine-based.

Parameters:

  • timeout number Wait timeout in seconds for each phase. (default 3)

Returns:

  1. int pid Process id.
  2. table status Exit status table.

Or

  1. nil On error.
  2. string Error message.
process:read_stdout ()
Read from process stdout.

See read

process:read_stderr ()
Read from process stderr.

See read

Class signal

Signal handle returned by sys.signal.

This object represents one signal listener created by sys.signal.

Call signal:close to stop listening and release underlying resources. The close operation is idempotent.

signal:close ()
Stop listening for the signal and release resources.

This closes the internal signalfd, cancels pending read operations, and restores the process signal mask for this signal. Calling this method multiple times is safe.

generated by LDoc 1.5.0 Last updated 2026-04-09 14:48:22