C API reference
The public contract in streamzet_product.h. This API controls the engine lifecycle.
stz_product_config
| Field | Type and requirement |
|---|---|
| engine_path | const char* · Absolute engine path |
| registration_file | const char* · Absolute path to an owner-only enrollment key file (0600). |
| ca_file | const char* · Absolute CA PEM path |
| state_directory | const char* · Absolute per-device persistent directory path (0700). |
| device_name | const char* · Nonempty UTF-8 name, at most 128 bytes |
Paths must be shorter than 1,024 bytes. Keep string pointers valid until start returns. The provisioning tool rejects control characters in names. Initialize the stz_product handle to {0}; do not copy it to share ownership.
| Field / API | Type / default | Contract |
|---|---|---|
| stz_product.pid | pid_t · 0 | Owned child PID; initialize the handle to {0}. poll resets it on exit/error. Do not assign, copy ownership or reap this child elsewhere. |
stz_product_start
int stz_product_start(stz_product *product,
const stz_product_config *config);| Return | Meaning |
|---|---|
| 0 | Child spawned. Enrollment and network connection proceed asynchronously. |
| EINVAL | Invalid argument, relative/oversized path, or device name |
| EALREADY | This handle already owns a running child |
| ECHILD | Could not inspect/reap the previous child |
| ENOENT / EACCES / other errno | posix_spawn or setup failure. Interpret the return value as an errno code. |
File-content and network-configuration errors can occur after spawn and cause the engine to exit. Keep polling after a successful start.
stz_product_poll
int stz_product_poll(stz_product *product, int *wait_status);| Return | Meaning |
|---|---|
| 1 | Child is still running; nonblocking. |
| 0 | Already stopped, or exited and reaped. The handle PID is reset to zero. |
| -1 | NULL handle or waitpid error |
wait_status may be NULL. When this call reaps a child, inspect the status with WIFEXITED/WEXITSTATUS or WIFSIGNALED/WTERMSIG from sys/wait.h. An already-stopped handle does not write a new exit status.
stz_product_stop
int stz_product_stop(stz_product *product);Requests SIGTERM if running. Returns zero on success or when already stopped; EINVAL for a NULL handle, ECHILD for a child-state error, or errno for signal delivery failure. This function does not wait for shutdown; reap the child with poll.
Threading and state ownership
Serialize all calls on a handle using one thread or external locking. The adapter passes credential file paths rather than key values, without evaluating arguments through a shell. The engine’s file lock rejects concurrent use of the same state directory.
Advanced: stz_config
| Field / API | Type / default | Contract |
|---|---|---|
| relay_host | const char* · required | 1–253 bytes of hostname characters (letters/digits/.-), no leading/trailing dot. No scheme/port/path; HTTPS/WSS port 443. |
| device_token | const char* · required | Exactly 64 hexadecimal characters: per-device secret, not enrollment or operator token. |
| ca_file | const char* · required | Absolute PEM path shorter than 1024 bytes. Valid CA file required at create time; TLS certificate/hostname checks always enabled. |
| allow_terminal | int · 0 | 0 denies interactive shell; nonzero opts in as the host OS user. |
| allow_commands | int · 0 | 0 denies Fleet commands; nonzero enables bounded execution. |
| device_id | const char* · NULL | Production: canonical 36-character lowercase UUID with hyphens. NULL selects legacy preview mode, not tenant enrollment. |
| registration_key | const char* · NULL | Production enrollment only; NULL/empty allowed after enrollment. Otherwise sz_live_ prefix, ≤128 bytes, alphanumeric/_/-. |
| device_name | const char* · required in production | Nonempty, ≤128 bytes when device_id is set; ignored in preview mode. |
| os_version | const char* · NULL | Production: ≤128 bytes, NULL becomes Linux embedded. Ignored in preview. |
Advanced lifecycle and bootstrap
| Field / API | Type / default | Contract |
|---|---|---|
| stz_create(config) | stz_client* / NULL | Copies config and initializes entropy/TLS. NULL on invalid config, allocation/entropy/CA/TLS failure. Does not enroll until run. |
| stz_run(client) | int · blocking | Host worker thread. Reconnects until stopped; 0 clean stop, -1 NULL/already running. One run per handle; one active TLS client/runtime per process is the qualified scope. |
| stz_stop(client) | void | Nonblocking wake; NULL is harmless, signal-handler safe. Join run before destroy. A stopped handle is not a fresh reconnectable handle; create a new one for a new run. |
| stz_destroy(client) | void | After run has joined only; frees resources and wipes copied secrets. NULL allowed. No concurrent access after destroy. |
| stz_prepare_entropy(path) | int | CLI bootstrap helper. Absolute seed path <1024 bytes under an owned 0700 directory; owned single-link regular 0600 file exactly 64 bytes. Rotate/fsync before TLS and new identity. 0 success, -1 failure. Never clone a seed. |
| stz_identity_lock(directory) | int fd / -1 | Existing absolute owned private directory; returns lock FD or -1. Hold through run; caller closes FD after shutdown. |
| stz_identity_load(directory, identity) | int | Hold the lock and prepare entropy first. Loads/creates identity, 0 success/-1 failure. identity is a caller-owned stz_identity*. |
| stz_identity.device_id | char[37] | 36-character lowercase UUID plus NUL; stable public ID. |
| stz_identity.secret | char[65] | 64 hexadecimal characters plus NUL; private per-device secret. Never log or export. |