cshared

Documentation

Overview

libitb — C ABI shared-library entry points for ITB.

Build:

go build -trimpath -buildmode=c-shared -o dist/linux-amd64/libitb.so ./cmd/cshared

The output is a shared library (.so / .dll / .dylib depending on GOOS) plus an auto-generated libitb.h header consumed by every language binding under bindings/<lang>/. Every entry point here is a thin //export wrapper around capi (see cmd/cshared/internal/capi/) — the real logic and tests live there.

Buffer convention. All input/output buffers are caller-allocated. For functions that produce variable-size output (Encrypt, Decrypt, HashName, Version, LastError) the caller passes (out, out_cap, &out_len). On success out_len is set to the number of bytes written; on ITB_ERR_BUFFER_TOO_SMALL out_len is set to the required capacity so the caller can resize and retry.

Handles. Seeds are exposed as opaque uintptr_t handles. Every ITB_NewSeed must be paired with exactly one ITB_FreeSeed. A handle from one seed cannot be mixed with seeds of a different native hash width inside one Encrypt / Decrypt call (returns ITB_ERR_SEED_WIDTH_MIX).

Threading. The library is safe for concurrent use across OS threads after seed handles are constructed; concurrent ITB_NewSeed / ITB_FreeSeed calls are also safe (cgo.Handle is internally synchronised). Process-wide config setters (ITB_SetBitSoup etc.) take effect for all subsequent Encrypt / Decrypt calls and are atomic.