Skip to content

API Reference

Jump to bottom
abduznik edited this page Jul 15, 2026 · 1 revision

API Reference

All public function signatures grouped by layer, with descriptions.

Initialization

sv_status_t sv_init(const char *base_path);
void        sv_shutdown(void);
  • sv_init — Initialize the library with a base path for metadata and magazine storage. Must be called before any other function.
  • sv_shutdown — Shut down the library, flush metadata to disk, and free all resources.

Layer 2 — Registration

sv_registration_t *sv_register(const sv_register_opts_t *opts, sv_status_t *out_status);

Create a new registration from a live save path and optional metadata. Returns an opaque handle and a persistent 8-character unique ID.

sv_status_t sv_update_register(sv_registration_t *reg, const sv_update_opts_t *opts, sv_update_result_t *out_result);

Mutate an existing registration (e.g. relocating live_save_path). Uses a set_mask bitfield to distinguish "leave unchanged" from "explicitly reset."

void sv_unregister(sv_registration_t *reg);

Drop the metadata record only. Entries become orphans; magazine and live files are untouched.

sv_status_t sv_list_registrations(sv_id_t *out_ids, size_t max_ids, size_t *out_count);

Enumerate all registration IDs into the caller-provided buffer.

sv_status_t sv_read_registration(const sv_id_t id, sv_registration_info_t *out_info);

Read full metadata for a registration by its ID.

Layer 4 — Local Save / Pull

sv_status_t sv_save(sv_registration_t *reg, const sv_save_opts_t *opts, sv_save_result_t *out_result);

Atomic copy-out from live_path into a new magazine entry. Computes content hash, runs dedup check, and triggers retention.

sv_status_t sv_pull(sv_registration_t *reg, const sv_pull_opts_t *opts, sv_pull_result_t *out_result);

Atomic copy-in of the most recent magazine entry to live_path. Conflict-checked by default.

sv_status_t sv_pull_select(sv_registration_t *reg, const sv_id_t entry_id, const sv_pull_opts_t *opts, sv_pull_result_t *out_result);

Atomic copy-in of a specific magazine entry to live_path. Pairs with sv_list_entries() for version picker UIs.

sv_status_t sv_list_entries(const sv_id_t reg_id, sv_id_t *out_ids, size_t max_ids, size_t *out_count);

Enumerate magazine entry IDs. Pass a null/sentinel reg_id to list orphaned entries.

sv_status_t sv_read_entry(const sv_id_t entry_id, sv_entry_info_t *out_info);

Read full metadata for a magazine entry by its ID.

sv_status_t sv_reparent_entry(const sv_id_t entry_id, const sv_id_t new_parent_reg_id);

Re-link an entry to a different registration. Used for ROM re-identification or orphan recovery.

sv_status_t sv_delete_entry(const sv_id_t entry_id);

The only manual hard-delete path. Never invoked implicitly by any other function.

Layer 6 — External Transport

sv_status_t sv_push_external(const sv_id_t entry_id, const sv_transport_t *transport);

Send one specific magazine entry out through the transport.

sv_status_t sv_pull_external(const sv_id_t reg_id, const sv_transport_t *transport, sv_pull_opts_t *pull_opts);

Fetch a remote save into a new local magazine entry. Never writes directly to the live path.

See also: Data-Types-Reference | Layer-4-Local-Save-and-Pull | Layer-6-External-Transport

libsavesync Wiki

Clone this wiki locally