GenServer managing a single OS process lifecycle.
Handles read/write on pipes, graceful shutdown, and exit status tracking.
Uses NIF-backed async I/O with enif_select for backpressure.
PTY mode
Pass pty: true to get a pseudo-terminal. This is for interactive and
long-running programs (shells, REPLs, curses apps). Key differences from
pipe mode:
- No independent stdin close — the PTY is a single bidirectional FD.
Use
kill/2to terminate the process. - The terminal echoes input back, so reads include what you wrote.
- Fast-exiting commands may lose output if you don't read immediately — the PTY buffer is torn down when the slave side closes.
- For simple commands, use pipe mode (the default).
Summary
Functions
Check if the process is alive.
Wait for the process to exit. Returns {:ok, exit_status}.
Returns a specification to start this module under a supervisor.
Close stdin pipe.
Send a signal to the OS process.
Get the OS PID.
Read from stdout. Blocks until data available or EOF.
Read from stderr.
Set PTY window size (rows, cols). Only works in PTY mode.
Get accumulated stats.
Returns the retained tail of consumed stderr.
Write to stdin.
Functions
Check if the process is alive.
Wait for the process to exit. Returns {:ok, exit_status}.
Returns a specification to start this module under a supervisor.
See Supervisor.
Close stdin pipe.
Send a signal to the OS process.
Get the OS PID.
Read from stdout. Blocks until data available or EOF.
Read from stderr.
Set PTY window size (rows, cols). Only works in PTY mode.
Get accumulated stats.
@spec stderr_tail(GenServer.server()) :: binary()
Returns the retained tail of consumed stderr.
In the default :consume stderr mode, stderr is drained to keep the child
from blocking on a full pipe; only the most-recent :stderr_tail_bytes
bytes (default 8 KB) are retained and returned here. Useful for diagnosing
why a command failed.
The tail is raw bytes and may begin mid-character if stderr was truncated,
so treat it as diagnostic text rather than guaranteed-valid UTF-8. Returns
"" in :disabled mode.
Write to stdin.