sysprims-session
Session and process group acquisition primitives for sysprims.
See the sysprims repository for documentation, release notes, and supported platform policy.
GPL-free session and process group management primitives.
Overview
This crate provides cross-platform primitives for session and process group management, replacing GPL-licensed tools:
| Function | Replaces | Original License |
|---|---|---|
setsid |
util-linux setsid | GPL-2.0 |
nohup |
coreutils nohup | GPL-3.0 |
Cleanroom Implementation
This implementation follows a cleanroom approach:
- Specification-driven: All behavior derived from POSIX specifications
- Permissive-only references: Only BSD/MIT code consulted for understanding
- No GPL code reviewed: util-linux and coreutils sources NOT consulted
- Behavioral validation: Tests compare against system tools (shell-out)
See Provenance Documentation below for detailed source records.
Platform Support
| Platform | setsid | nohup | setpgid | getpgid | getsid | Notes |
|---|---|---|---|---|---|---|
| Linux | Y | Y | Y | Y | Y | Full support via POSIX |
| macOS | Y | Y | Y | Y | Y | Full support via POSIX |
| FreeBSD | Y | Y | Y | Y | Y | Full support via POSIX |
| Windows | - | - | - | - | - | No equivalent concept* |
* Windows uses different process isolation model (Job Objects, sessions via
CreateProcessAsUser). These are not direct equivalents and would be a
different abstraction. WSL provides POSIX session semantics.
API
High-Level Functions
use ;
// Run command in new session (detached from terminal)
let result = run_setsid?;
// Run command immune to SIGHUP
let result = run_nohup?;
// Wait for completion
let result = run_setsid?;
Low-Level Functions
use ;
// Get current session ID
let sid = getsid?; // 0 = current process
// Get current process group
let pgid = getpgid?;
// Create new process group (self as leader)
setpgid?;
Spawn-Time Acquisition Receipt
External spawners that own the child and terminal handles can prepare a
single-use session hook before fork, install it in place of any other
setsid/setpgid acquirer, validate its positive acknowledgement, and pass the
receipt to the timeout crate's explicit external-child ownership boundary:
use CommandExt;
use Command;
use prepare_session_acquisition;
let = prepare_session_acquisition?;
let mut command = new;
unsafe
let child = command.spawn?;
let receipt = pending.into_receipt?;
The prepared hook carries a shared one-byte token, so reusing the configured
command for a second spawn fails closed before a second setsid. Dropping the
pending receipt closes its private descriptors. Linux creates those descriptors
with atomic close-on-exec/nonblocking flags; other Unix targets use the
platform pipe/fcntl fallback.
The hook performs one setsid and one fixed-size nonblocking write in the
post-fork/pre-exec child. It performs no allocation, locking, formatting,
blocking, or panic. The opaque receipt is not cloneable and cannot be minted
from a PID or post-spawn observation. Consumers pair it with the owned child via
sysprims_timeout::contain_acquired_session.
Design Notes
setsid
POSIX Specification: setsid(2)
The setsid() function creates a new session if the calling process is not a
process group leader. The calling process becomes:
- The session leader of the new session
- The process group leader of a new process group
- Has no controlling terminal
Implementation approach:
Parent Process
|
+-- fork() --> Child Process
|
+-- setsid() // Creates new session
|
+-- exec(command)
The fork is implicit in Command::spawn(). We use pre_exec to call setsid()
in the child after fork but before exec.
Why fork first?: A process group leader cannot call setsid() (EPERM).
By forking, the child is guaranteed not to be a process group leader.
nohup
POSIX Specification: nohup
The nohup utility invokes a command with SIGHUP ignored:
- Set SIGHUP disposition to SIG_IGN
- If stdout is terminal, redirect to
nohup.outor$HOME/nohup.out - If stderr is terminal and stdout was redirected, redirect stderr too
- Execute the command
Implementation approach:
// In pre_exec (after fork, before exec):
signal;
// Before spawn (in parent):
if stdout.is_tty
Provenance
setsid
Primary Sources (Specifications):
- POSIX.1-2017 setsid(2): https://pubs.opengroup.org/onlinepubs/9699919799/functions/setsid.html
- FreeBSD setsid(2) man page (BSD License)
- Apple Darwin setsid(2) (APSL)
Reference Implementations (Consulted for Understanding):
- setsid-macosx - BSD-2-Clause
- ersatz-setsid - MIT
NOT Consulted:
- util-linux setsid.c (GPL-2.0)
nohup
Primary Sources (Specifications):
- POSIX.1-2017 nohup utility: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/nohup.html
- FreeBSD nohup(1) man page (BSD License)
Reference Implementations (Consulted for Understanding):
- OpenBSD nohup.c (ISC License)
NOT Consulted:
- GNU coreutils nohup.c (GPL-3.0)
Behavioral Comparison Tests
The test suite includes behavioral comparison against system tools:
This validates we match expected behavior without reviewing GPL source code.
Future Work
- CLI subcommand (
sysprims session setsid <cmd>) - Full
daemonize()function (double-fork, chdir, umask, close fds) -
disownequivalent (remove from job table) - Windows: Document that Job Objects /
CreateProcessAsUserare different abstractions
License
MIT OR Apache-2.0 (same as sysprims workspace)