Skip to content
Welcome to the new CppUtils documentation!

Namespace: CppUtils::System

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

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

Execution outcome status recorded inside an isolated process.

using CppUtils::System::CrashCallback = std::function<void(const CrashInformation&)>;
using CppUtils::System::ProcessId = pid_t;
using CppUtils::System::Library = void*;
using CppUtils::System::Handle = std::intptr_t;
auto CppUtils::System::InvalidHandle;
void defaultCrashHandler(const CrashInformation& information);
void installCrashHandler(CrashCallback customHandler=defaultCrashHandler);
int throwErrno(int value, std::string_view message="");
std::expected<int, std::system_error> expectErrno(int value, std::string_view message="");
std::string_view signalToString(Signal signal) noexcept;

Returns the symbolic name of a typed Signal.

ParameterDescription
signalStrongly-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

std::string_view signalToExplanation(Signal signal) noexcept;

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

ParameterDescription
signalStrongly-typed signal enumerator.

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

See also: Linux manual: signal(7)

ProcessId fork();

Creates a new child process via fork().

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

Sends a signal to a process using kill().

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

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

void quickExit(int exitCode = 0) noexcept;

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

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

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

ParameterDescription
functionRoutine to execute in the child process.
timeoutMaximum allowable execution duration (0ms for unlimited).
onBeforeExecutionOptional hook invoked inside the child process immediately after fork.

Returns: Successful execution result or failure details.

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