GALANTHUS / ABI FUNCTION REFERENCE
gln_save_local_cache
Declared in <galanthus/c_api/gln_capi.h>.
GLN_API gln_status_t GLN_CALL gln_save_local_cache(
const char* in_cache_path,
const char* in_key_path_or_null,
const uint8_t* in_payload,
size_t in_payload_len,
gln_error_t* out_error);
Purpose
Encrypts and durably saves one local-cache payload using the Galanthus-owned local-cache protected-key purpose.
Use this helper for optional application cache data that must not be written as plaintext beside the encrypted cache file.
Nullable parameter slots (in_key_path_or_null, out_error) may be passed as NULL; all other non-value parameters follow the nullability shown in the table.
in_payload may be NULL only when in_payload_len is zero.
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_cache_path | input | const char* | nonnull | borrowed |
in_key_path_or_null | input | const char* | nullable | borrowed |
in_payload | input | const uint8_t* | nullable | borrowed |
in_payload_len | input | size_t | value | value |
out_error | output | gln_error_t* | nullable | caller_allocated_output |
Path Semantics
in_cache_path is the required encrypted cache payload path. in_key_path_or_null optionally selects the sidecar key path; passing NULL or an empty string uses the Galanthus default derived from in_cache_path.
Storage Security
The function owns the local-cache crypto domain. Callers do not supply arbitrary magic, purpose, nonce, or key material.
Payload writes use the storage layer's file lock and atomic durable-write helpers. Each save uses a fresh nonce, so saving identical plaintext produces different ciphertext.
Failure Cases
The call returns GLN_ERR_INVALID_ARG when in_cache_path is NULL or empty, or when in_payload is NULL with a nonzero in_payload_len.
File, permission, lock, key, encryption, or durable-write failures return a non-OK status through the normal error slot.