2424 */
2525
2626/*
27- * retrace public API — see the modernization plan.md
27+ * retrace public API.
28+ *
29+ * Every function declared here is implemented and exported by the
30+ * library. test/unit/test_public_api.c enforces that contract at
31+ * build time (it dlsyms each symbol and fails the build if any is
32+ * missing).
33+ *
34+ * A larger engine/script-builder/config scaffold was declared here
35+ * from the v2.0.0 modernization plan but never implemented; the
36+ * declarations were removed in v2.5.0 because a header that
37+ * declares unlinked symbols breaks consumers at link time. See
38+ * docs/adr/0014-public-api-matches-implementation.md for the
39+ * decision and the re-introduction path.
2840 *
2941 * Design constraints (see docs/adr/0008-opaque-public-types-for-abi.md):
3042 * - All types are opaque handles. Struct definitions are internal.
3143 * - All functions return int (0 on success, negative on error).
32- * - All output is caller-allocated with a size parameter, or returned as
33- * a `const char *` owned by the engine.
34- * - ABI-stable from v2.0.0.
44+ * - All output is caller-allocated with a size parameter, or returned
45+ * as a `const char *` owned by the engine.
3546 */
3647
3748#ifndef RETRACE_RETRACE_H
3849#define RETRACE_RETRACE_H
3950
4051#include <stddef.h>
41- #include <stdint.h>
42-
43- #include <retrace/version.h>
4452
4553#ifdef __cplusplus
4654extern "C" {
4755#endif
4856
49- /*
50- * Visibility annotation. Public symbols are tagged RETRACE_API; everything
51- * else is hidden by default (set via CMAKE_C_VISIBILITY_PRESET=hidden).
52- */
57+ /* Export/visibility. */
5358#if defined(_WIN32 ) && defined(RETRACE_SHARED )
5459# define RETRACE_API __declspec(dllexport)
5560#elif defined(_WIN32 ) && defined(RETRACE_STATIC )
@@ -62,20 +67,6 @@ extern "C" {
6267# define RETRACE_INTERNAL
6368#endif
6469
65- /* Opaque handles — definitions live in src/core/internal/. */
66- typedef struct retrace_engine retrace_engine_t ;
67- typedef struct retrace_script retrace_script_t ;
68- typedef struct retrace_intercept_rule retrace_intercept_rule_t ;
69- typedef struct retrace_action_params retrace_action_params_t ;
70-
71- /* Result of an action callback. Drives engine dispatch. */
72- typedef enum {
73- RETRACE_ACTION_OK = 0 ,
74- RETRACE_ACTION_SKIP_CALL = 1 ,
75- RETRACE_ACTION_HANDLED = 2 ,
76- RETRACE_ACTION_ERROR = -1 ,
77- } retrace_action_result_t ;
78-
7970/* Status codes for public APIs. */
8071typedef enum {
8172 RETRACE_OK = 0 ,
@@ -91,47 +82,14 @@ typedef enum {
9182
9283/* ----------------------------------------------------------------- *
9384 * Version
85+ *
86+ * Compile-time: the RETRACE_VERSION_* macros (include/retrace/version.h)
87+ * and RETRACE_VERSION_ATLEAST(maj, min, pat). Runtime: the two
88+ * functions below, both returning library-owned static strings.
9489 */
9590RETRACE_API const char * retrace_version (void );
9691RETRACE_API const char * retrace_version_info (void );
9792
98- /* ----------------------------------------------------------------- *
99- * Engine lifecycle
100- *
101- * The engine is the top-level owner of: the prototype registry, the action
102- * registry, the backend handle, the active script, per-thread invocation
103- * state, and the real-impl table (libc function pointers used internally
104- * to avoid reentrancy).
105- *
106- * One engine per process is typical. Multi-engine is supported but each
107- * engine has independent registries; prototypes are global (linker-section
108- * scanned) so they are shared.
109- */
110- RETRACE_API retrace_status_t retrace_engine_create (retrace_engine_t * * out );
111- RETRACE_API retrace_status_t retrace_engine_destroy (retrace_engine_t * eng );
112-
113- RETRACE_API retrace_status_t retrace_engine_set_script (
114- retrace_engine_t * eng , retrace_script_t * script );
115- RETRACE_API retrace_status_t retrace_engine_get_script (
116- retrace_engine_t * eng , const retrace_script_t * * out );
117-
118- RETRACE_API retrace_status_t retrace_engine_set_option (
119- retrace_engine_t * eng ,
120- const char * key ,
121- const char * value );
122-
123- /* ----------------------------------------------------------------- *
124- * Backend selection
125- *
126- * Backends self-register at constructor time. The engine selects one by
127- * probing each registered backend; `retrace_engine_select_backend` forces
128- * a specific one. See include/retrace/backend.h (the modernization plan/03).
129- */
130- RETRACE_API const char * const * retrace_engine_list_backends (
131- retrace_engine_t * eng , size_t * count );
132- RETRACE_API retrace_status_t retrace_engine_select_backend (
133- retrace_engine_t * eng , const char * name );
134-
13593/* ----------------------------------------------------------------- *
13694 * Process attach
13795 *
@@ -164,95 +122,6 @@ RETRACE_API retrace_status_t retrace_attach_process(int pid);
164122RETRACE_API retrace_status_t retrace_list_backends (
165123 const char * const * * out_names , size_t * out_count );
166124
167- /* ----------------------------------------------------------------- *
168- * Programmatic script builder
169- *
170- * Build a script in C without parsing a file. Equivalent to the JSON path
171- * but with no serialization in between.
172- */
173- RETRACE_API retrace_script_t * retrace_script_new (retrace_engine_t * eng );
174- RETRACE_API void retrace_script_free (retrace_script_t * script );
175- RETRACE_API retrace_status_t retrace_script_validate (
176- retrace_script_t * script , char * err_buf , size_t err_len );
177-
178- RETRACE_API retrace_status_t retrace_script_add_intercept (
179- retrace_script_t * script ,
180- const char * func_glob ,
181- retrace_intercept_rule_t * * out );
182-
183- RETRACE_API retrace_action_params_t * retrace_action_params_new (void );
184- RETRACE_API void retrace_action_params_free (retrace_action_params_t * params );
185-
186- RETRACE_API retrace_status_t retrace_action_params_set_int (
187- retrace_action_params_t * params ,
188- const char * name , long long value );
189- RETRACE_API retrace_status_t retrace_action_params_set_double (
190- retrace_action_params_t * params ,
191- const char * name , double value );
192- RETRACE_API retrace_status_t retrace_action_params_set_string (
193- retrace_action_params_t * params ,
194- const char * name , const char * value );
195-
196- RETRACE_API retrace_status_t retrace_intercept_rule_add_action (
197- retrace_intercept_rule_t * rule ,
198- const char * action_name ,
199- retrace_action_params_t * params );
200-
201- /* ----------------------------------------------------------------- *
202- * Config parsing
203- *
204- * Delegates to the named config source (typically "json" or "text").
205- * Sources self-register at constructor time. See the modernization plan/04.
206- */
207- RETRACE_API retrace_status_t retrace_config_parse_file (
208- retrace_engine_t * eng ,
209- const char * source_name ,
210- const char * path ,
211- retrace_script_t * * out );
212-
213- RETRACE_API retrace_status_t retrace_config_parse_buffer (
214- retrace_engine_t * eng ,
215- const char * source_name ,
216- const char * buf , size_t len ,
217- retrace_script_t * * out );
218-
219- RETRACE_API const char * const * retrace_config_list_sources (
220- retrace_engine_t * eng , size_t * count );
221-
222- /* ----------------------------------------------------------------- *
223- * Inspection
224- *
225- * Used by the CLI (`retrace prototypes list`, etc.) and by tooling that
226- * wants to introspect the engine. Output arrays are NULL-terminated and
227- * owned by the engine until the next call to the same function.
228- */
229- RETRACE_API const char * const * retrace_engine_list_prototypes (
230- retrace_engine_t * eng , size_t * count );
231- RETRACE_API const char * const * retrace_engine_list_actions (
232- retrace_engine_t * eng , size_t * count );
233-
234- RETRACE_API retrace_status_t retrace_engine_describe_prototype (
235- retrace_engine_t * eng ,
236- const char * func_name ,
237- char * * out_desc ); /* caller frees with retrace_free() */
238-
239- RETRACE_API retrace_status_t retrace_engine_describe_action (
240- retrace_engine_t * eng ,
241- const char * action_name ,
242- char * * out_desc );
243-
244- RETRACE_API void retrace_free (void * ptr );
245-
246- /* ----------------------------------------------------------------- *
247- * Error reporting
248- *
249- * The most recent error for the calling thread is held in thread-local
250- * storage. `retrace_last_error` returns the message (owned by the engine
251- * until the next call on the same thread).
252- */
253- RETRACE_API const char * retrace_last_error (retrace_engine_t * eng );
254- RETRACE_API int retrace_last_error_code (retrace_engine_t * eng );
255-
256125#ifdef __cplusplus
257126}
258127#endif
0 commit comments