C API Reference

The C API (exposed via a cbindgen-generated header) provides stable, binary-compatible access to the core rsx_core functionality from C, C++, Python (ctypes / cffi), R (.Call), and other languages.

It follows a simple contract (see also the :doc:`Architecture </explanation/architecture>` page):

  • All public types are #[repr(C)].

  • Functions return rsx_status_t first.

  • Thread-local error details via rsx_last_error().

  • Opaque handles for complex state (e.g. popmaps, marker tables in future).

  • Naming: rsx_ prefix, SCREAMING_SNAKE_CASE for enums, _t suffix for structs.

1 Building the header

cargo build --manifest-path radsex-core/Cargo.toml --features gen-header
# Produces radsex-core/include/rsx.h

The header is a build artifact (gitignored) and must be regenerated after changes to the C API surface in radsex-core/src/c_api/.

2 API Reference

3 Error handling

All fallible functions return an rsx_status_t. On failure, call rsx_last_error() on the same thread to retrieve a human-readable message (the pointer is valid only until the next C API call on that thread).

4 Cross-language notes

  • **C/C++**: Link against the cdylib (librsx_core.so / .dylib / .dll) and include the header.

  • **Python**: Use ctypes or cffi to load the library and call the functions (see the R-integration how-to for a similar pattern).

  • **R**: The .so can be used via .Call() or dyn.load (work in progress; see the issue tracker).

For the underlying Rust implementation of these functions and types, see the :doc:`Rust API Reference <rust-api>`.