Ownership and API reference

The C header is authoritative for signatures and layouts. The Rust exports identify the public Rust API. Generate local Rust documentation for your pinned checkout with cargo doc -p termy_core --no-deps.

API map

C constructors without a config use runtime defaults; they do not implicitly load all of the user's application settings. Choose the config-aware constructor when you want that behavior.

Allocation ownership

Zero-initialize output structs and check the returned status before reading them. Free an existing successful result before reusing its output variable: the next call does not release the previous allocation for you.

Never free a nested byte field separately from its owning batch. Do not edit returned allocation pointers, lengths, or capacities; the free functions need them to reconstruct Rust-owned allocations. Copying an owning C struct does not create another owned allocation: freeing both copies double-frees the same data.

TermyFfiByteSlice is borrowed and has no free function. Its lifetime comes from the call or callback that supplies it. Standalone TermyFfiBytes from an encoder or config string getter is owned; TermyFfiBytes inside a batch belongs to that batch. The containing API determines ownership, not just the field's type.

Threading and shutdown

A TermyFfiTerminal handle is not internally synchronized at the FFI boundary. Serialize every call taking that handle, including reads and encoding calls. Separate handles can be driven independently. The only documented exceptions are termy_terminal_wait_for_wakeup and termy_terminal_notify_wakeup, which access the wake channel rather than terminal state.

A safe shutdown sequence for a host with a waiter is:

1. Stop scheduling new terminal work and set the host's shutdown flag.
2. Let any in-flight serialized terminal call finish.
3. Call termy_terminal_notify_wakeup so the waiter can observe shutdown.
4. Join the waiter; ensure queued callbacks/tasks cannot access the handle.
5. Call termy_terminal_free exactly once and clear the host pointer.

Notify alone is insufficient: the waiter must exit rather than immediately waiting again. Never free while any call, including a blocking wait, is still using the handle. Clipboard callbacks cannot re-enter it even on the same thread.

Rust types have their own synchronization and borrowing contracts; the C concurrency rule is not a substitute for reading the Rust method docs. In particular, locked visitors must not re-enter the same terminal.

Status codes

Not every function returns every status. For example, OK from an encoder can mean no bytes were produced; OK from a search can mean no matches. Function success is not proof that the child has processed input or exited successfully.

On failure, do not consume the output as a successful result. Report the API name and status, and use a controlled teardown/recreation policy after an unexpected panic. Panic catching does not make invalid pointers, mismatched headers, or concurrent handle access safe.

Adjacent host APIs

The header also exposes settings persistence, CLI installation, native config getters, and tmux control helpers. They are not required to embed one terminal. Settings and installation calls have filesystem side effects. A tmux control handle is a different type with its own lifetime: close it with termy_tmux_control_close, release notification batches with termy_tmux_control_notifications_free, and release standalone command output with termy_buffer_free.

Keep session-manager features separate from the terminal frame loop. Use the matching header and implementation when adopting these additional APIs.