Module ffi 

C ABI for readcon-db (always linked into cdylib/staticlib).

Status codes mirror a small subset of readcon-core style (negative = error).

Constants

RKRDB_ERR

RKRDB_NOT_FOUND

RKRDB_NULL

RKRDB_OK

Functions

rkrdb_append_trajectory^⚠

rkrdb_close^⚠

rkrdb_cook_frame^⚠

Opt-in cook: derive RCSO into frames_soa from CON text in frames (CON remains authority).

rkrdb_delete_cooked^⚠

Drop cooked tier only; CON text and indexes unchanged.

rkrdb_frame_formula^⚠

Canonical composition formula for a stored frame (same as core index_proj). Writes into buf (NUL-terminated). Returns RKRDB_OK, RKRDB_NOT_FOUND, RKRDB_ERR, or buffer size need as positive? On success returns RKRDB_OK; if buflen too small returns RKRDB_ERR and sets last_error.

rkrdb_frame_hash^⚠

Hash frame blob at key; writes 16 LE bytes to out_hash16.

rkrdb_get_forces^⚠

Prefer cooked forces when present; writes N×3 doubles. Sets *out_has_forces 0/1.

rkrdb_get_frame_text^⚠

Copy frame CON text into buf (NUL-terminated). Returns length excluding NUL, or error code.

rkrdb_get_positions^⚠

Prefer cooked positions (no CON parse on hit); else parse CON. Writes *out_natoms * 3 doubles into out_xyz (row-major N×3). capacity_atoms is max N.

rkrdb_has_valid_cooked^⚠

Returns 1 if valid RCSO present, 0 if missing/corrupt, negative on error.

rkrdb_last_error^⚠

Last error message (thread-safe snapshot into caller buffer). Returns bytes written excluding NUL, or -1 if truncated / null.

rkrdb_open^⚠

Open corpus directory. On success writes opaque handle id to out_id (>=0). Returns RKRDB_OK or error code.

rkrdb_recook_all^⚠

Cook every frame that has CON text (recook_all).

rkrdb_reindex^⚠

Rebuild secondary indexes from authoritative frame blobs.

rkrdb_result_count^⚠

rkrdb_result_key^⚠

Write traj_id and frame_idx for result index i (0-based).

rkrdb_select_basic^⚠

Select by required symbol (optional) and natoms range (use 0, UINT32_MAX for any). Results stored internally; use rkrdb_result_count / rkrdb_result_key.

rkrdb_select_campaign^⚠

Campaign select: composition formula (NUL-terminated, may be null), optional fmax window. use_fmax_range non-zero applies fmax_min/max. Flags: bit0 forces, bit1 velocities, bit2 energy. Element constraints: pass elem_sym + elem_count + elem_exact (1=exact, 0=min) for one pair (null skips).

rkrdb_select_hash^⚠

Select by exact xxHash3-128 (16 bytes LE).

rkrdb_select_meta^⚠

Metadata / section filters. Pass use_energy_range=0 to ignore energy bounds. Flags: bit0=require_forces, bit1=require_velocities, bit2=require_energy.

rkrdb_xxh3_128^⚠

xxHash3-128 of arbitrary bytes (LE 16 bytes) — for clients hashing off-line blobs.