GALANTHUS / ABI FUNCTION REFERENCE
gln_init_runtime
Declared in <galanthus/c_api/gln_capi.h>.
GLN_API gln_status_t GLN_CALL gln_init_runtime(
const gln_init_options_t* in_options_or_null,
gln_error_t* out_error);
Purpose
Initializes process-wide Galanthus C ABI runtime state.
Call this before opening backends, creating file-backed stores, or running operations that depend on runtime configuration.
Return
Returns GLN_OK on success and a non-OK gln_status_t value on failure.
| Type | Nullability | Ownership |
|---|---|---|
gln_status_t | value | value |
Parameters
| Name | Direction | Type | Nullability | Ownership |
|---|---|---|---|---|
in_options_or_null | input | const gln_init_options_t* | nullable | borrowed |
out_error | output | gln_error_t* | nullable | caller_allocated_output |
Options
Pass NULL for in_options_or_null to use the current defaults and runtime path environment variables, or initialize a gln_init_options_t with gln_default_init_options before filling fields.
On an initialization attempt before the runtime is already initialized, supplied options must have struct_size == sizeof(gln_init_options_t). A mismatch returns GLN_ERR_INVALID_ARG through the status boundary.
log_level defaults to 1. plugin_dir_or_null, dump_dir_or_null, and log_file_path_or_null are optional UTF-8 filesystem path strings; NULL or an empty string means the field is absent at the options layer.
When an options struct is supplied, absent path fields stay absent and do not fall back to GALANTHUS_PLUGIN_PATH, GALANTHUS_DUMP_DIR, or GALANTHUS_LOG_FILE. Those environment variables are consulted only when in_options_or_null is NULL.
Lifecycle
A successful first call records the resolved process state and opens the configured log file path when one is available.
Opening the log file is best-effort; if the file cannot be opened, initialization still succeeds and logging falls back to stderr.
Repeat calls after successful initialization are idempotent and return GLN_OK without applying new options.
Call gln_shutdown_runtime when the process is done with the library to tear down this process-wide state.