infix.h File Reference

The public interface for the infix FFI library. More...

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

Include dependency graph for infix.h:

Go to the source code of this file.

Classes
struct	infix_version_t
	A structure representing the semantic version of the library. More...
struct	infix_type_t
	A semi-opaque structure that describes a C type. More...
struct	infix_struct_member_t
	Describes a single member of a C struct or union. More...
struct	infix_function_argument_t
	Describes a single argument to a C function. More...
struct	infix_registry_iterator_t
	An iterator for traversing a type registry. More...
struct	infix_error_details_t
	Provides detailed, thread-local information about the last error that occurred. More...
union	infix_direct_value_t
	A union to hold any primitive value returned by a scalar marshaller. More...
struct	infix_direct_arg_handler_t
	A struct containing all the necessary handlers for a single function argument. More...

Macros
#define	INFIX_MAJOR   0
#define	INFIX_MINOR   1
#define	INFIX_PATCH   4
#define	_INFIX_HAS_C_ATTRIBUTE(x)   0
#define	INFIX_API
	Symbol visibility macro.
#define	INFIX_NODISCARD
	A compatibility macro for the C23 [[nodiscard]] attribute.
#define	_DEFAULT_SOURCE
#define	_POSIX_C_SOURCE   200809L
#define	infix_malloc   malloc
	A macro that can be defined to override the default malloc function.
#define	infix_calloc   calloc
	A macro that can be defined to override the default calloc function.
#define	infix_realloc   realloc
	A macro that can be defined to override the default realloc function.
#define	infix_free   free
	A macro that can be defined to override the default free function.
#define	infix_memcpy   memcpy
	A macro that can be defined to override the default memcpy function.
#define	infix_memset   memset
	A macro that can be defined to override the default memset function.

Typedefs
typedef struct infix_type_t	infix_type
	A semi-opaque object describing a C type's memory layout and calling convention. See infix_type_t for details.
typedef struct infix_struct_member_t	infix_struct_member
	A semi-opaque object describing a member of a C struct or union. See infix_struct_member_t for details.
typedef struct infix_function_argument_t	infix_function_argument
	A semi-opaque object describing an argument to a C function. See infix_function_argument_t for details.
typedef struct infix_forward_t	infix_forward_t
	An opaque handle to a forward (C-to-native) trampoline. Created by infix_forward_create and variants.
typedef struct infix_reverse_t	infix_reverse_t
	An opaque handle to a reverse (native-to-C) trampoline, also known as a callback or closure.
typedef infix_reverse_t	infix_context_t
	An alias for infix_reverse_t, used to clarify its role as a context object in closure handlers.
typedef struct infix_arena_t	infix_arena_t
	An opaque handle to an arena allocator, used for efficient grouped memory allocations.
typedef struct infix_library_t	infix_library_t
	An opaque handle to a dynamically loaded shared library (.so, .dll, .dylib).
typedef struct infix_registry_t	infix_registry_t
	An opaque handle to a named type registry.
typedef void(*	infix_unbound_cif_func) (void *, void *, void **)
	A function pointer type for an unbound forward trampoline.
typedef void(*	infix_cif_func) (void *, void **)
	A function pointer type for a bound forward trampoline.
typedef void(*	infix_closure_handler_fn) (infix_context_t *, void *, void **)
	A function pointer type for a generic closure handler.
typedef struct infix_registry_iterator_t	infix_registry_iterator_t
typedef void(*	infix_direct_cif_func) (void *, void **)
	A function pointer for a direct marshalling forward trampoline.
typedef infix_direct_value_t(*	infix_marshaller_fn) (void *source_object)
	A function pointer for a custom marshaller for scalar types.
typedef void(*	infix_aggregate_marshaller_fn) (void *source_object, void *dest_buffer, const infix_type *type)
	A function pointer for a custom marshaller for aggregate types (structs/unions).
typedef void(*	infix_writeback_fn) (void *source_object, void *c_data_ptr, const infix_type *type)
	A function pointer for a "write-back" handler for out/in-out parameters.

Enumerations
enum	infix_type_category {   INFIX_TYPE_PRIMITIVE , INFIX_TYPE_POINTER , INFIX_TYPE_STRUCT , INFIX_TYPE_UNION ,   INFIX_TYPE_ARRAY , INFIX_TYPE_REVERSE_TRAMPOLINE , INFIX_TYPE_ENUM , INFIX_TYPE_COMPLEX ,   INFIX_TYPE_VECTOR , INFIX_TYPE_NAMED_REFERENCE , INFIX_TYPE_VOID }
	Enumerates the fundamental categories of types that infix can represent. More...
enum	infix_primitive_type_id {   INFIX_PRIMITIVE_BOOL , INFIX_PRIMITIVE_UINT8 , INFIX_PRIMITIVE_SINT8 , INFIX_PRIMITIVE_UINT16 ,   INFIX_PRIMITIVE_SINT16 , INFIX_PRIMITIVE_UINT32 , INFIX_PRIMITIVE_SINT32 , INFIX_PRIMITIVE_UINT64 ,   INFIX_PRIMITIVE_SINT64 , INFIX_PRIMITIVE_UINT128 , INFIX_PRIMITIVE_SINT128 , INFIX_PRIMITIVE_FLOAT ,   INFIX_PRIMITIVE_DOUBLE , INFIX_PRIMITIVE_LONG_DOUBLE }
	Enumerates the supported primitive C types. More...
enum	infix_aggregate_category_t { INFIX_AGGREGATE_STRUCT , INFIX_AGGREGATE_UNION }
	Specifies whether a named type reference refers to a struct or a union. More...
enum	infix_status {   INFIX_SUCCESS = 0 , INFIX_ERROR_ALLOCATION_FAILED , INFIX_ERROR_INVALID_ARGUMENT , INFIX_ERROR_UNSUPPORTED_ABI ,   INFIX_ERROR_LAYOUT_FAILED , INFIX_ERROR_PROTECTION_FAILED , INFIX_ERROR_ }
	Enumerates the possible status codes returned by infix API functions. More...
enum	infix_print_dialect_t { INFIX_DIALECT_SIGNATURE , INFIX_DIALECT_ITANIUM_MANGLING , INFIX_DIALECT_MSVC_MANGLING }
	Specifies the output format for printing types and function signatures. More...
enum	infix_error_category_t {   INFIX_CATEGORY_NONE , INFIX_CATEGORY_GENERAL , INFIX_CATEGORY_ALLOCATION , INFIX_CATEGORY_PARSER ,   INFIX_CATEGORY_ABI }
	Enumerates the high-level categories of errors that can occur. More...
enum	infix_error_code_t {   INFIX_CODE_SUCCESS = 0 , INFIX_CODE_UNKNOWN , INFIX_CODE_NULL_POINTER , INFIX_CODE_MISSING_REGISTRY ,   INFIX_CODE_OUT_OF_MEMORY = 100 , INFIX_CODE_EXECUTABLE_MEMORY_FAILURE , INFIX_CODE_PROTECTION_FAILURE , INFIX_CODE_INVALID_ALIGNMENT ,   INFIX_CODE_UNEXPECTED_TOKEN = 200 , INFIX_CODE_UNTERMINATED_AGGREGATE , INFIX_CODE_INVALID_KEYWORD , INFIX_CODE_MISSING_RETURN_TYPE ,   INFIX_CODE_INTEGER_OVERFLOW , INFIX_CODE_RECURSION_DEPTH_EXCEEDED , INFIX_CODE_EMPTY_MEMBER_NAME , INFIX_CODE_EMPTY_SIGNATURE ,   INFIX_CODE_UNSUPPORTED_ABI = 300 , INFIX_CODE_TYPE_TOO_LARGE , INFIX_CODE_UNRESOLVED_NAMED_TYPE , INFIX_CODE_INVALID_MEMBER_TYPE ,   INFIX_CODE_LAYOUT_FAILED , INFIX_CODE_LIBRARY_NOT_FOUND = 400 , INFIX_CODE_SYMBOL_NOT_FOUND , INFIX_CODE_LIBRARY_LOAD_FAILED }
	Enumerates specific error codes. More...

Functions
INFIX_API INFIX_NODISCARD infix_version_t	infix_get_version (void)
	Retrieves the version of the infix library linked at runtime.
INFIX_API INFIX_NODISCARD infix_registry_t *	infix_registry_create (void)
	Creates a new, empty named type registry.
INFIX_API INFIX_NODISCARD infix_registry_t *	infix_registry_clone (const infix_registry_t *)
	Creates a deep copy of an existing type registry.
INFIX_API void	infix_registry_destroy (infix_registry_t *)
	Destroys a type registry and frees all associated memory.
INFIX_API INFIX_NODISCARD infix_status	infix_register_types (infix_registry_t *, const char *)
	Parses a string of type definitions and adds them to a registry.
INFIX_API INFIX_NODISCARD infix_status	infix_registry_print (char *, size_t, const infix_registry_t *)
	Serializes all defined types within a registry into a single, human-readable string.
INFIX_API INFIX_NODISCARD infix_registry_iterator_t	infix_registry_iterator_begin (const infix_registry_t *)
	Initializes an iterator for traversing the types in a registry.
INFIX_API INFIX_NODISCARD bool	infix_registry_iterator_next (infix_registry_iterator_t *)
	Advances the iterator to the next defined type in the registry.
INFIX_API INFIX_NODISCARD const char *	infix_registry_iterator_get_name (const infix_registry_iterator_t *)
	Gets the name of the type at the iterator's current position.
INFIX_API INFIX_NODISCARD const infix_type *	infix_registry_iterator_get_type (const infix_registry_iterator_t *)
	Gets the infix_type object of the type at the iterator's current position.
INFIX_API INFIX_NODISCARD bool	infix_registry_is_defined (const infix_registry_t *, const char *)
	Checks if a type with the given name is fully defined in the registry.
INFIX_API INFIX_NODISCARD const infix_type *	infix_registry_lookup_type (const infix_registry_t *, const char *)
	Retrieves the canonical infix_type object for a given name from the registry.
INFIX_API INFIX_NODISCARD infix_registry_t *	infix_registry_create_in_arena (infix_arena_t *arena)
	Creates a new named type registry that allocates from a user-provided arena.
INFIX_API INFIX_NODISCARD infix_status	infix_forward_create (infix_forward_t **, const char *, void *, infix_registry_t *)
	Creates a "bound" forward trampoline from a signature string.
INFIX_API INFIX_NODISCARD infix_status	infix_forward_create_unbound (infix_forward_t **, const char *, infix_registry_t *)
	Creates an "unbound" forward trampoline from a signature string.
INFIX_API INFIX_NODISCARD infix_status	infix_forward_create_in_arena (infix_forward_t **, infix_arena_t *, const char *, void *, infix_registry_t *)
	Creates a "bound" forward trampoline within a user-provided arena.
INFIX_API INFIX_NODISCARD infix_status	infix_reverse_create_callback (infix_reverse_t **, const char *, void *, infix_registry_t *)
	Creates a type-safe reverse trampoline (callback).
INFIX_API INFIX_NODISCARD infix_status	infix_reverse_create_closure (infix_reverse_t **, const char *, infix_closure_handler_fn, void *, infix_registry_t *)
	Creates a generic reverse trampoline (closure) for stateful callbacks.
INFIX_API INFIX_NODISCARD infix_status	infix_signature_parse (const char *, infix_arena_t **, infix_type **, infix_function_argument **, size_t *, size_t *, infix_registry_t *)
	Parses a full function signature string into its constituent parts.
INFIX_API INFIX_NODISCARD infix_status	infix_type_from_signature (infix_type **, infix_arena_t **, const char *, infix_registry_t *)
	Parses a signature string representing a single data type.
INFIX_API INFIX_NODISCARD infix_library_t *	infix_library_open (const char *)
	Opens a dynamic library and returns a handle to it.
INFIX_API void	infix_library_close (infix_library_t *)
	Closes a dynamic library handle.
INFIX_API INFIX_NODISCARD void *	infix_library_get_symbol (infix_library_t *, const char *)
	Retrieves the address of a symbol (function or variable) from a loaded library.
INFIX_API INFIX_NODISCARD infix_status	infix_read_global (infix_library_t *, const char *, const char *, void *, infix_registry_t *)
	Reads the value of a global variable from a library into a buffer.
INFIX_API INFIX_NODISCARD infix_status	infix_write_global (infix_library_t *, const char *, const char *, void *, infix_registry_t *)
	Writes data from a buffer into a global variable in a library.
INFIX_API INFIX_NODISCARD infix_status	infix_forward_create_manual (infix_forward_t **, infix_type *, infix_type **, size_t, size_t, void *)
	Creates a bound forward trampoline from infix_type objects.
INFIX_API INFIX_NODISCARD infix_status	infix_forward_create_unbound_manual (infix_forward_t **, infix_type *, infix_type **, size_t, size_t)
	Creates an unbound forward trampoline from infix_type objects.
INFIX_API INFIX_NODISCARD infix_status	infix_reverse_create_callback_manual (infix_reverse_t **, infix_type *, infix_type **, size_t, size_t, void *)
	Creates a type-safe reverse trampoline (callback) from infix_type objects.
INFIX_API INFIX_NODISCARD infix_status	infix_reverse_create_closure_manual (infix_reverse_t **, infix_type *, infix_type **, size_t, size_t, infix_closure_handler_fn, void *)
	Creates a generic reverse trampoline (closure) from infix_type objects.
INFIX_API void	infix_forward_destroy (infix_forward_t *)
	Destroys a forward trampoline and frees all associated memory.
INFIX_API void	infix_reverse_destroy (infix_reverse_t *)
	Destroys a reverse trampoline and frees all associated memory.
INFIX_API INFIX_NODISCARD infix_type *	infix_type_create_primitive (infix_primitive_type_id)
	Creates a static descriptor for a primitive C type.
INFIX_API INFIX_NODISCARD infix_type *	infix_type_create_pointer (void)
	Creates a static descriptor for a generic pointer (void*).
INFIX_API INFIX_NODISCARD infix_status	infix_type_create_pointer_to (infix_arena_t *, infix_type **, infix_type *)
	Creates a new pointer type that points to a specific type.
INFIX_API INFIX_NODISCARD infix_type *	infix_type_create_void (void)
	Creates a static descriptor for the void type.
INFIX_API INFIX_NODISCARD infix_status	infix_type_create_struct (infix_arena_t *, infix_type **, infix_struct_member *, size_t)
	Creates a new struct type from an array of members, calculating layout automatically.
INFIX_API INFIX_NODISCARD infix_status	infix_type_create_packed_struct (infix_arena_t *, infix_type **, size_t, size_t, infix_struct_member *, size_t)
	Creates a new packed struct type with a user-specified layout.
INFIX_API INFIX_NODISCARD infix_status	infix_type_create_union (infix_arena_t *, infix_type **, infix_struct_member *, size_t)
	Creates a new union type from an array of members.
INFIX_API INFIX_NODISCARD infix_status	infix_type_create_array (infix_arena_t *, infix_type **, infix_type *, size_t)
	Creates a new fixed-size array type.
INFIX_API infix_status	infix_type_create_flexible_array (infix_arena_t *, infix_type **, infix_type *)
	Creates a flexible array member type ([?:type]).
INFIX_API INFIX_NODISCARD infix_status	infix_type_create_enum (infix_arena_t *, infix_type **, infix_type *)
	Creates a new enum type with a specified underlying integer type.
INFIX_API INFIX_NODISCARD infix_status	infix_type_create_named_reference (infix_arena_t *, infix_type **, const char *, infix_aggregate_category_t)
	Creates a placeholder for a named type to be resolved by a registry.
INFIX_API INFIX_NODISCARD infix_status	infix_type_create_complex (infix_arena_t *, infix_type **, infix_type *)
	Creates a new _Complex number type.
INFIX_API INFIX_NODISCARD infix_status	infix_type_create_vector (infix_arena_t *, infix_type **, infix_type *, size_t)
	Creates a new SIMD vector type.
INFIX_API infix_struct_member	infix_type_create_member (const char *, infix_type *, size_t)
	A factory function to create an infix_struct_member.
INFIX_API infix_struct_member	infix_type_create_bitfield_member (const char *, infix_type *, size_t, uint8_t)
	A factory function to create a bitfield infix_struct_member.
INFIX_API INFIX_NODISCARD infix_arena_t *	infix_arena_create (size_t)
	Creates a new memory arena.
INFIX_API void	infix_arena_destroy (infix_arena_t *)
	Destroys an arena and frees all memory allocated from it.
INFIX_API INFIX_NODISCARD void *	infix_arena_alloc (infix_arena_t *, size_t, size_t)
	Allocates a block of memory from an arena.
INFIX_API INFIX_NODISCARD void *	infix_arena_calloc (infix_arena_t *, size_t, size_t, size_t)
	Allocates and zero-initializes a block of memory from an arena.
INFIX_API INFIX_NODISCARD infix_status	infix_type_print (char *, size_t, const infix_type *, infix_print_dialect_t)
	Serializes an infix_type object graph back into a signature string.
INFIX_API INFIX_NODISCARD infix_status	infix_function_print (char *, size_t, const char *, const infix_type *, const infix_function_argument *, size_t, size_t, infix_print_dialect_t)
	Serializes a function signature's components into a string.
INFIX_API INFIX_NODISCARD infix_unbound_cif_func	infix_forward_get_unbound_code (infix_forward_t *)
	Gets the callable function pointer from an unbound forward trampoline.
INFIX_API INFIX_NODISCARD infix_cif_func	infix_forward_get_code (infix_forward_t *)
	Gets the callable function pointer from a bound forward trampoline.
INFIX_API INFIX_NODISCARD void *	infix_reverse_get_code (const infix_reverse_t *)
	Gets the native, callable C function pointer from a reverse trampoline.
INFIX_API INFIX_NODISCARD void *	infix_reverse_get_user_data (const infix_reverse_t *)
	Gets the user-provided data pointer from a closure context.
INFIX_API INFIX_NODISCARD size_t	infix_forward_get_num_args (const infix_forward_t *)
	Gets the total number of arguments for a forward trampoline.
INFIX_API INFIX_NODISCARD size_t	infix_forward_get_num_fixed_args (const infix_forward_t *)
	Gets the number of fixed (non-variadic) arguments for a forward trampoline.
INFIX_API INFIX_NODISCARD const infix_type *	infix_forward_get_return_type (const infix_forward_t *)
	Gets the return type for a forward trampoline.
INFIX_API INFIX_NODISCARD const infix_type *	infix_forward_get_arg_type (const infix_forward_t *, size_t)
	Gets the type of a specific argument for a forward trampoline.
INFIX_API INFIX_NODISCARD size_t	infix_reverse_get_num_args (const infix_reverse_t *)
	Gets the total number of arguments for a reverse trampoline.
INFIX_API INFIX_NODISCARD const infix_type *	infix_reverse_get_return_type (const infix_reverse_t *)
	Gets the return type for a reverse trampoline.
INFIX_API INFIX_NODISCARD size_t	infix_reverse_get_num_fixed_args (const infix_reverse_t *)
	Gets the number of fixed (non-variadic) arguments for a reverse trampoline.
INFIX_API INFIX_NODISCARD const infix_type *	infix_reverse_get_arg_type (const infix_reverse_t *, size_t)
	Gets the type of a specific argument for a reverse trampoline.
INFIX_API INFIX_NODISCARD const char *	infix_type_get_name (const infix_type *)
	Gets the semantic alias of a type, if one exists.
INFIX_API INFIX_NODISCARD infix_type_category	infix_type_get_category (const infix_type *)
	Gets the fundamental category of a type.
INFIX_API INFIX_NODISCARD size_t	infix_type_get_size (const infix_type *)
	Gets the size of a type in bytes.
INFIX_API INFIX_NODISCARD size_t	infix_type_get_alignment (const infix_type *)
	Gets the alignment requirement of a type in bytes.
INFIX_API INFIX_NODISCARD size_t	infix_type_get_member_count (const infix_type *)
	Gets the number of members in a struct or union type.
INFIX_API INFIX_NODISCARD const infix_struct_member *	infix_type_get_member (const infix_type *, size_t)
	Gets a specific member from a struct or union type.
INFIX_API INFIX_NODISCARD const char *	infix_type_get_arg_name (const infix_type *, size_t)
	Gets the name of a specific argument from a function type.
INFIX_API INFIX_NODISCARD const infix_type *	infix_type_get_arg_type (const infix_type *, size_t)
	Gets the type of a specific argument from a function type.
INFIX_API infix_error_details_t	infix_get_last_error (void)
	Retrieves detailed information about the last error that occurred on the current thread.
INFIX_API INFIX_NODISCARD infix_status	infix_forward_create_direct (infix_forward_t **out_trampoline, const char *signature, void *target_function, infix_direct_arg_handler_t *handlers, infix_registry_t *registry)
	Creates a forward trampoline with direct, JIT-bound marshalling.
INFIX_API INFIX_NODISCARD infix_direct_cif_func	infix_forward_get_direct_code (infix_forward_t *trampoline)
	Gets the callable function pointer from a direct marshalling trampoline.

Detailed Description

The public interface for the infix FFI library.

Copyright (c) 2025 Sanko Robinson

This source code is dual-licensed under the Artistic License 2.0 or the MIT License. You may choose to use this code under the terms of either license.

SPDX-License-Identifier: (Artistic-2.0 OR MIT)

The documentation blocks within this file are licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).

SPDX-License-Identifier: CC-BY-4.0

Macro Definition Documentation

_DEFAULT_SOURCE

#define _DEFAULT_SOURCE

_POSIX_C_SOURCE

#define _POSIX_C_SOURCE   200809L

Function Documentation

infix_get_version()

INFIX_API INFIX_NODISCARD infix_version_t infix_get_version

(

void

)

Retrieves the version of the infix library linked at runtime.

This function allows applications to verify that the version of the library they are linked against matches the headers they were compiled with. This is particularly useful when loading infix as a shared library/DLL to detect version mismatches.

Returns

An infix_version_t structure containing the major, minor, and patch numbers.

An infix_version_t structure containing the major, minor, and patch numbers.