Provisional API: This reference documents current compiler behavior. Compatibility is not yet promised.

src/utils.x

System utilities for environment discovery and child processes.

Functions

Functions

process_run

int process_run(char **argv, String *output, String *errors)

Starts and waits for one direct child action. After capture setup succeeds, output, status, and failure behavior follow process_start and ChildProcess.wait. A partial capture setup failure returns no defined status; its closed field remains recorded.

Source: src/utils.x:311

process_start

ChildProcess process_start(char **argv)

Starts a direct child action and captures stdout and stderr separately. argv must be a NULL-terminated vector with a non-NULL first element and need remain valid only through this call. The returned handle is Scope-owned. An invalid action or fork failure is recorded as pid == -1 with start_error; an execvp failure is a child exit with status 127. Capture setup failure closes any stream that opened, but a partial failure leaves that closed field recorded and does not produce a waitable handle.

Source: src/utils.x:236

worker_exit

void worker_exit(int status)

Attempts to flush process streams and terminates a worker with status. Flush failure is ignored. This function does not return and does not run atexit handlers. Those belong to the parent process and would close its log and process-lifetime Scopes twice.

Source: src/utils.x:333

worker_fork

long worker_fork(void)

Forks a worker that continues the current program with inherited state. Returns zero in the child, its PID in the parent, or -1 on fork failure. The call attempts to flush all process streams before the fork so successfully flushed bytes cannot be written by both processes. Flush failure is ignored. The child must leave through worker_exit.

Source: src/utils.x:322

worker_wait

int worker_wait(long pid)

Waits once for pid and returns its shell-style status. Normal exit returns the worker status, a signal returns 128 + signal, and a wait failure returns -1. Interrupted waits are retried.

Source: src/utils.x:342

x2c_cpp_include_dirs

List x2c_cpp_include_dirs(void)

Returns the borrowed preprocessor List <root>/src, then <root>/lib. Returns NULL before environment setup.

Source: src/utils.x:89

x2c_default_include_dirs

List x2c_default_include_dirs(void)

Returns the borrowed default include List containing <root>/include. Returns NULL before environment setup.

Source: src/utils.x:84

x2c_driver_error

void x2c_driver_error(const char *message)

Prints x2c: error: <message> to stderr and exits with status 2.

Source: src/utils.x:92

x2c_get_executable

String x2c_get_executable(void)

Returns the borrowed resolved executable path, or NULL when unavailable.

Source: src/utils.x:62

x2c_get_root

String x2c_get_root(void)

Returns the borrowed repository root, or NULL before it is configured.

Source: src/utils.x:59

x2c_initialize_environment

void x2c_initialize_environment(const char *argv0)

Initializes compiler paths and default include Lists once. The executable is resolved from the host, argv0, or PATH; repository discovery then walks from that path and the current directory before falling back to .. An already configured root leaves all state unchanged.

Source: src/utils.x:29

x2c_path_dir

String x2c_path_dir(String path)

Returns the directory part of path, or “.” when it has no slash.

Source: src/utils.x:65

x2c_path_stem

String x2c_path_stem(String path)

Returns the final path component without its final extension. A leading dot belongs to the name, so .x2crc keeps its spelling while parse.x becomes parse. A null or empty final component returns the empty String.

Source: src/utils.x:76

x2c_set_root

void x2c_set_root(String root)

Overrides the repository root and rebuilds its default include Lists. root is retained without copying. It and the rebuilt values must remain valid until the next override or the process no longer uses them.

Source: src/utils.x:51

ChildProcess

ChildProcess.wait

int ChildProcess.wait(ChildProcess c, String *output, String *errors)

Waits for process, then reads and closes its captured streams. Both output pointers are required and are cleared before validation. On a returning call they receive canonical Strings or the empty String. The result is the exit status, 128 + signal, or -1 for invalid arguments, an invalid action, fork failure, or wait failure. An execvp failure returns 127 with its diagnostic in errors; an invalid action or fork failure places start_error there instead. A partial capture setup failure is not a valid input to this method.

Raises: <io-fail>, <bad-arg>, <size-limit>, or <alloc-fail> while reading either capture as a String. A failure may leave capture streams open.

Source: src/utils.x:287

Public types

ChildProcess

typedef struct ChildProcess { long pid; File output, errors, String start_error; } *ChildProcess

Holds a Scope-owned child process and its stdout and stderr captures. process_start records a successful child with a nonnegative pid and a local start failure with pid == -1 and start_error. Only successful capture setup leaves live streams for ChildProcess.wait; such a child must be waited exactly once.

Source: src/utils.x:19

Design notes

Finds the repository, prints the driver’s fatal error line, and starts child processes. Process paths remain argv data; stdout, stderr, and the child status are captured independently.