Functions & utilities

Namespace: CppUtils::System

Public enums

Signal

enum class Signal {
    Abort = SIGABRT,
    Alarm = SIGALRM,
    Bus = SIGBUS,
    Child = SIGCHLD,
    Continue = SIGCONT,
    FloatingPointException = SIGFPE,
    Hangup = SIGHUP,
    IllegalInstruction = SIGILL,
    Interrupt = SIGINT,
    Io = SIGIO,
    Kill = SIGKILL,
    Pipe = SIGPIPE,
    ProfilingTimer = SIGPROF,
    Quit = SIGQUIT,
    SegmentationFault = SIGSEGV,
    Stop = SIGSTOP,
    System = SIGSYS,
    Terminate = SIGTERM,
    Trap = SIGTRAP,
    TerminalStop = SIGTSTP,
    TerminalInput = SIGTTIN,
    TerminalOutput = SIGTTOU,
    Urgent = SIGURG,
    User1 = SIGUSR1,
    User2 = SIGUSR2,
    VirtualAlarm = SIGVTALRM,
    WindowChange = SIGWINCH,
    CpuTimeLimit = SIGXCPU,
    FileSizeLimit = SIGXFSZ
};

Strongly-typed enumeration representing process signals across POSIX and non-POSIX platforms.

Under POSIX systems (Linux, macOS), enumerators map directly to system macros provided by <csignal>.

Under non-POSIX systems (such as Windows), the C Runtime only defines ISO C signals (SIGABRT, SIGFPE, SIGILL, SIGINT, SIGSEGV, SIGTERM). Standard POSIX values (IEEE Std 1003.1 / Linux x86-64 ABI) are provided as fallback constants to guarantee compile-time compatibility with cross-platform test runners, event watchers, and matchers without requiring platform-specific #ifdef guards at call sites.

See also: Linux manual: signal(7)

See also: POSIX.1-2017: signal.h

See also: Microsoft Learn: Signal Constants

ExecutionStatus

enum class ExecutionStatus {
    Success = 0,
    Failure = 1
};

Execution outcome status recorded inside an isolated process.

Public types

CrashCallback

using CppUtils::System::CrashCallback = typedef std::function<void(const CrashInformation&)>;

ProcessId

using CppUtils::System::ProcessId = typedef pid_t;

Library

using CppUtils::System::Library = typedef void*;

Handle

using CppUtils::System::Handle = typedef std::intptr_t;

Constants & variables

constexpr auto CppUtils::System::InvalidHandle;

Public functions

auto defaultCrashHandler(const CrashInformation& information) -> void;

auto installCrashHandler(CrashCallback customHandler=defaultCrashHandler) -> void;

auto throwErrno(int value, std::string_view message="") -> int;

auto expectErrno(int value, std::string_view message="") -> std::expected<int, std::system_error>;

constexpr auto signalToString(Signal signal) noexcept -> std::string_view;

Returns the symbolic name of a typed Signal.

Parameter	Description
signal	Strongly-typed signal enumerator.

Returns: String view of the signal name (e.g. “SIGSEGV”, “SIGKILL”), or “Unknown”.

See also: Linux manual: signal(7)

See also: POSIX.1-2017: signal.h

constexpr auto signalToExplanation(Signal signal) noexcept -> std::string_view;

Returns a human-readable diagnostic explanation for a termination signal.

Parameter	Description
signal	Strongly-typed signal enumerator.

Returns: Detailed explanation of the signal’s probable cause, or empty string view if unknown.

See also: Linux manual: signal(7)

auto fork() -> ProcessId;

Creates a new child process via fork().

auto kill(ProcessId processIdentifier, Signal signal=Signal::Kill) -> void;

Sends a signal to a process using kill().

auto wait(ProcessId processIdentifier, int options = 0) -> ProcessStatus;

Waits for state changes in a child process via waitpid().

auto quickExit(int exitCode = 0) noexcept -> void;

Terminates the calling process immediately without calling atexit or global destructors.

auto runIsolated(std::invocable auto&& function, std::chrono::milliseconds timeout=std::chrono::milliseconds{0}, std::function<void()> onBeforeExecution={}) -> std::expected<IsolatedExecutionResult, IsolatedExecutionFailure>;

Executes a callable in an isolated child process, supervising execution and handling completion, timeout, and crash signals.

Parameter	Description
function	Routine to execute in the child process.
timeout	Maximum allowable execution duration (0ms for unlimited).
onBeforeExecution	Optional hook invoked inside the child process immediately after fork.

Returns: Successful execution result or failure details.

auto createAnonymousFile(std::string_view name, unsigned int flags = 0) -> FileDescriptor;