Environment

Runtime metadata about the active execution context, plus process-level environment signal handling. More...

Collaboration diagram for Environment:

Data Structures
struct	sys_env_arg_flag_t
	Describes a single command-line argument flag. More...

Macros
#define	SYS_ENV_ARG_CAPACITY   16
	Maximum number of positional (non-flag) command-line arguments sys_env_arg_parse() can record.

Typedefs
typedef void(*	sys_env_signal_callback_t) (sys_env_signal_t signal)
	Callback function type for handling environment signals. More...
typedef struct sys_env_arg_flag_t	sys_env_arg_flag_t
	Describes a single command-line argument flag. More...
typedef struct sys_env_arg_t	sys_env_arg_t
	The result of a successful sys_env_arg_parse() call. More...

Enumerations
enum	sys_env_signal_t { sys_env_signal_none = 0, sys_env_signal_term = 1u, sys_env_signal_int = 2u, sys_env_signal_quit = 4u }
	Environment signal types. More...
enum	sys_env_arg_type_t {   sys_env_arg_type_bool = 1, sys_env_arg_type_string = 2, sys_env_arg_type_int = 3, sys_env_arg_type_uint = 4,   sys_env_arg_type_float = 5 }
	Argument flag value types. More...

Methods
bool	sys_env_signalhandler (sys_env_signal_t mask, sys_env_signal_callback_t callback)
	Set a handler for environment signals. More...
const char *	sys_env_serial (void)
	Return a unique identifier for the current environment. More...
const char *	sys_env_name (void)
	Return the name of the current environment. More...
const char *	sys_env_system (void)
	Return the system identifier for the current environment. More...
const char *	sys_env_version (void)
	Return the version of the current environment. More...
void	sys_env_set_args (int argc, char *argv[])
	Replace the argc/argv that sys_env_arg_parse() reads. More...
sys_env_arg_t *	sys_env_arg_parse (sys_env_arg_flag_t *flags)
	Parse the process's command-line arguments against a set of flags. More...
size_t	sys_env_arg_count (sys_env_arg_t *args)
	Return the number of positional arguments. More...
const char *	sys_env_arg_string (sys_env_arg_t *args, size_t index)
	Return the value of a positional argument by index. More...
bool	sys_env_arg_usage (sys_env_arg_flag_t *flags, sys_iostream_t *stream)
	Print the usage information for the command-line flags. More...
bool	sys_env_arg_parse_bool (sys_env_arg_t *args, const char *name, bool *value)
	Look up a parsed flag's value as a boolean. More...
bool	sys_env_arg_parse_int32 (sys_env_arg_t *args, const char *name, int32_t *value)
	Look up a parsed flag's value as a 32-bit signed integer. More...
bool	sys_env_arg_parse_uint32 (sys_env_arg_t *args, const char *name, uint32_t *value)
	Look up a parsed flag's value as a 32-bit unsigned integer. More...
bool	sys_env_arg_parse_int64 (sys_env_arg_t *args, const char *name, int64_t *value)
	Look up a parsed flag's value as a 64-bit signed integer. More...
bool	sys_env_arg_parse_uint64 (sys_env_arg_t *args, const char *name, uint64_t *value)
	Look up a parsed flag's value as a 64-bit unsigned integer. More...
bool	sys_env_arg_parse_float32 (sys_env_arg_t *args, const char *name, float *value)
	Look up a parsed flag's value as a 32-bit single-precision floating-point number. More...
bool	sys_env_arg_parse_float64 (sys_env_arg_t *args, const char *name, double *value)
	Look up a parsed flag's value as a 64-bit double-precision floating-point number. More...
size_t	sys_env_arg_parse_string (sys_env_arg_t *args, const char *name, char *value, size_t cap)
	Look up a parsed flag's value as a string. More...

Detailed Description

Runtime metadata about the active execution context, plus process-level environment signal handling.

The Environment module provides runtime metadata about the active execution context and a lightweight interface for handling process-level environment signals.

Metadata methods return stable identifiers that help applications report or route behavior per environment, including:

• sys_env_serial() for unique identity information when available.
• sys_env_name() for process/program naming.
• sys_env_system() for platform identification.
• sys_env_version() for runtime version reporting.

Signal integration is exposed through sys_env_signalhandler(), which registers a callback for termination-related signals. This is useful for graceful shutdown, cancellation, and runloop exit coordination.

Signal handling notes:

• Only one callback registration is active at a time.
• Signal support may vary by platform.
• Callbacks may run in constrained contexts; keep handlers minimal and non-blocking.

Typical flow:

1. Register a signal callback during startup (if needed).
2. Read environment metadata for diagnostics/logging/capability decisions.
3. On shutdown, clear signal callbacks or let deinit paths unregister.

Typedef Documentation

sys_env_arg_flag_t

typedef struct sys_env_arg_flag_t sys_env_arg_flag_t

Describes a single command-line argument flag.

On input to sys_env_arg_parse(), long_name/short_name/type describe the flag to look for, and value holds its default. On return, value holds the matched argument's value if the flag was present on the command line, or is left untouched at its default otherwise.

sys_env_arg_t

typedef struct sys_env_arg_t sys_env_arg_t

The result of a successful sys_env_arg_parse() call.

A single, process-wide instance - there is only ever one process command line to parse, so this is never pool-allocated. Returned by sys_env_arg_parse() and passed back into the sys_env_arg_*() accessors that read positional arguments or matched flag values.

Definition at line 125 of file env.h.

sys_env_signal_callback_t

typedef void(* sys_env_signal_callback_t) (sys_env_signal_t signal)

Callback function type for handling environment signals.

Parameters

signal

The type of signal that was received.

Definition at line 69 of file env.h.

Enumeration Type Documentation

sys_env_arg_type_t

enum sys_env_arg_type_t

Argument flag value types.

Identifies which kind of value a sys_env_arg_flag_t expects. Used by sys_env_arg_parse() to validate a matched argument's value.

Enumerator
sys_env_arg_type_bool	Argument flag expects a boolean value.
sys_env_arg_type_string	Argument flag expects a string value.
sys_env_arg_type_int	Argument flag expects an integer value.
sys_env_arg_type_uint	Argument flag expects an unsigned integer value.
sys_env_arg_type_float	Argument flag expects a floating-point value.

Definition at line 78 of file env.h.

             {
  sys_env_arg_type_bool = 1,   
  sys_env_arg_type_string = 2, 
  sys_env_arg_type_int = 3,    
  sys_env_arg_type_uint = 4,   
  sys_env_arg_type_float = 5,  
} sys_env_arg_type_t;

sys_env_signal_t

enum sys_env_signal_t

Environment signal types.

Enumeration of signal types that can be received from the environment or operating system. These signals typically indicate termination or interrupt requests that applications should handle gracefully.

Enumerator
sys_env_signal_none	No signal.
sys_env_signal_term	Termination request from the environment.
sys_env_signal_int	Interrupt request from the environment.
sys_env_signal_quit	Quit request from the environment.

Definition at line 57 of file env.h.

             {
  sys_env_signal_none = 0,  
  sys_env_signal_term = 1u, 
  sys_env_signal_int = 2u,  
  sys_env_signal_quit = 4u, 
} sys_env_signal_t;

Function Documentation

sys_env_arg_count()

size_t sys_env_arg_count

(

sys_env_arg_t *

args

)

Return the number of positional arguments.

Parameters

args	The parse result returned by sys_env_arg_parse().

Returns

The number of positional arguments.

sys_env_arg_parse()

sys_env_arg_t* sys_env_arg_parse

(

sys_env_arg_flag_t *

flags

)

Parse the process's command-line arguments against a set of flags.

Parameters

flags

Array of flag descriptors to match against. Use a zero-initialized sys_env_arg_flag_t (long_name == NULL) to mark the end of the array - there is no separate count parameter.

Returns

A pointer to the parse result on success or NULL on a malformed or unrecognized argument.

Reads from the argc/argv captured by sys_init(). Non-flag argv entries are collected as positional arguments, in order. Flags are matched against the provided descriptors, either by long name (--flag) or short name (-f).

Boolean flags are treated as true if present, or --no-\<flag\> to explicitly set them to false. If not present, the default value is used, or 'false' if no default is specified.

When a flag contains a "=" character, the portion after the "=" is treated as the flag's value, else the next argv entry is treated as the value. The argument '-' by itself is skipped and indicates the remaining arguments are positional.

sys_env_arg_parse_bool()

bool sys_env_arg_parse_bool	(	sys_env_arg_t *	args,
		const char *	name,
		bool *	value
	)

Look up a parsed flag's value as a boolean.

Parameters

args	The parse result returned by sys_env_arg_parse().
name	The flag's long or short name.
value	Pointer to a boolean variable where the result will be stored.

Returns

true if the flag was found and successfully parsed, or false if the flag wasn't found or sys_env_arg_parse() hasn't succeeded yet.

sys_env_arg_parse_float32()

bool sys_env_arg_parse_float32	(	sys_env_arg_t *	args,
		const char *	name,
		float *	value
	)

Look up a parsed flag's value as a 32-bit single-precision floating-point number.

Parameters

args	The parse result returned by sys_env_arg_parse().
name	The flag's long or short name.
value	Pointer to a 32-bit single-precision floating-point variable where the result will be stored.

Returns

true if the flag was found and successfully parsed, or false if the flag wasn't found or sys_env_arg_parse() hasn't succeeded yet.

sys_env_arg_parse_float64()

bool sys_env_arg_parse_float64	(	sys_env_arg_t *	args,
		const char *	name,
		double *	value
	)

Look up a parsed flag's value as a 64-bit double-precision floating-point number.

Parameters

args	The parse result returned by sys_env_arg_parse().
name	The flag's long or short name.
value	Pointer to a 64-bit double-precision floating-point variable where the result will be stored.

Returns

true if the flag was found and successfully parsed, or false if the flag wasn't found or sys_env_arg_parse() hasn't succeeded yet.

sys_env_arg_parse_int32()

bool sys_env_arg_parse_int32	(	sys_env_arg_t *	args,
		const char *	name,
		int32_t *	value
	)

Look up a parsed flag's value as a 32-bit signed integer.

Parameters

args	The parse result returned by sys_env_arg_parse().
name	The flag's long or short name.
value	Pointer to a 32-bit signed integer variable where the result will be stored.

Returns

true if the flag was found and successfully parsed, or false if the flag wasn't found or sys_env_arg_parse() hasn't succeeded yet.

sys_env_arg_parse_int64()

bool sys_env_arg_parse_int64	(	sys_env_arg_t *	args,
		const char *	name,
		int64_t *	value
	)

Look up a parsed flag's value as a 64-bit signed integer.

Parameters

args	The parse result returned by sys_env_arg_parse().
name	The flag's long or short name.
value	Pointer to a 64-bit signed integer variable where the result will be stored.

Returns

true if the flag was found and successfully parsed, or false if the flag wasn't found or sys_env_arg_parse() hasn't succeeded yet.

sys_env_arg_parse_string()

size_t sys_env_arg_parse_string	(	sys_env_arg_t *	args,
		const char *	name,
		char *	value,
		size_t	cap
	)

Look up a parsed flag's value as a string.

Parameters

args	The parse result returned by sys_env_arg_parse().
name	The flag's long or short name.
value	A buffer to store the flag's value. If NULL only the required buffer size is returned.
cap	The capacity of the buffer.

Returns

The number of bytes written to the buffer, or 0 if the flag wasn't found or sys_env_arg_parse() hasn't succeeded yet.

sys_env_arg_parse_uint32()

bool sys_env_arg_parse_uint32	(	sys_env_arg_t *	args,
		const char *	name,
		uint32_t *	value
	)

Look up a parsed flag's value as a 32-bit unsigned integer.

Parameters

args	The parse result returned by sys_env_arg_parse().
name	The flag's long or short name.
value	Pointer to a 32-bit unsigned integer variable where the result will be stored.

Returns

true if the flag was found and successfully parsed, or false if the flag wasn't found or sys_env_arg_parse() hasn't succeeded yet.

sys_env_arg_parse_uint64()

bool sys_env_arg_parse_uint64	(	sys_env_arg_t *	args,
		const char *	name,
		uint64_t *	value
	)

Look up a parsed flag's value as a 64-bit unsigned integer.

Parameters

args	The parse result returned by sys_env_arg_parse().
name	The flag's long or short name.
value	Pointer to a 64-bit unsigned integer variable where the result will be stored.

Returns

true if the flag was found and successfully parsed, or false if the flag wasn't found or sys_env_arg_parse() hasn't succeeded yet.

sys_env_arg_string()

const char* sys_env_arg_string	(	sys_env_arg_t *	args,
		size_t	index
	)

Return the value of a positional argument by index.

Parameters

args	The parse result returned by sys_env_arg_parse().
index	The index of the positional argument.

Returns

The value of the positional argument, or NULL if the index is out of bounds.

sys_env_arg_usage()

bool sys_env_arg_usage	(	sys_env_arg_flag_t *	flags,
		sys_iostream_t *	stream
	)

Print the usage information for the command-line flags.

Parameters

flags	Array of flag descriptors to display usage for, terminated the same way as sys_env_arg_parse()'s own flags parameter.
stream	The stream to print the usage information to.

Returns

true if the usage information was successfully printed, false otherwise.

sys_env_name()

const char* sys_env_name

(

void

)

Return the name of the current environment.

Returns

The name of the running program or environment.

sys_env_serial()

const char* sys_env_serial

(

void

)

Return a unique identifier for the current environment.

Returns

A serial number or other unique identifier as a string.

sys_env_set_args()

void sys_env_set_args	(	int	argc,
		char *	argv[]
	)

Replace the argc/argv that sys_env_arg_parse() reads.

Parameters

argc	Argument count.
argv	Argument vector.

sys_init() already calls this once with the process's real argc/argv - most programs never need to call it themselves. It exists for the rare case of validating sys_env_arg_parse() against several different command lines in one process (e.g. a test), without re-running sys_init()'s other, one-time module setup (stdio, the default arena, ...) again for each one.

sys_env_signalhandler()

bool sys_env_signalhandler	(	sys_env_signal_t	mask,
		sys_env_signal_callback_t	callback
	)

Set a handler for environment signals.

Parameters

mask	Bitmask of sys_env_signal_t values to handle, or zero to handle all supported signals.
callback	Callback to invoke when a signal is received, or NULL to disable signal handling.

Returns

true when the handler was updated successfully, false when signal handling is not supported on the current platform.

Only one signal handler can be active at a time. Setting a new handler replaces any previously registered handler.

Not all platforms support all signal types. Embedded platforms may have limited or no signal support.

The signal handler may be called from interrupt context on some platforms. Keep the callback simple and avoid blocking operations, memory allocation, or complex system calls.

sys_env_system()

const char* sys_env_system

(

void

)

Return the system identifier for the current environment.

Returns

A system identifier string such as "linux", "darwin", or a Pico board name when running on Pico targets.

sys_env_version()

const char* sys_env_version

(

void

)

Return the version of the current environment.

Returns

The version of the running program or environment.