infix.h File Reference

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

#include "common/compat_c23.h"
#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_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_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   1
#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
	An opaque handle to a registry iterator. Created by infix_registry_iterator_begin.
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_OUT_OF_MEMORY = 100 , INFIX_CODE_EXECUTABLE_MEMORY_FAILURE ,   INFIX_CODE_PROTECTION_FAILURE , 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_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
c23_nodiscard infix_registry_t *	infix_registry_create (void)
	Creates a new, empty named type registry.
void	infix_registry_destroy (infix_registry_t *)
	Destroys a type registry and frees all associated memory.
c23_nodiscard infix_status	infix_register_types (infix_registry_t *, const char *)
	Parses a string of type definitions and adds them to a registry.
c23_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.
c23_nodiscard infix_registry_iterator_t	infix_registry_iterator_begin (const infix_registry_t *)
	Initializes an iterator for traversing the types in a registry.
c23_nodiscard bool	infix_registry_iterator_next (infix_registry_iterator_t *)
	Advances the iterator to the next defined type in the registry.
c23_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.
c23_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.
c23_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.
c23_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.
c23_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.
c23_nodiscard infix_status	infix_forward_create (infix_forward_t **, const char *, void *, infix_registry_t *)
	Creates a "bound" forward trampoline from a signature string.
c23_nodiscard infix_status	infix_forward_create_unbound (infix_forward_t **, const char *, infix_registry_t *)
	Creates an "unbound" forward trampoline from a signature string.
c23_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.
c23_nodiscard infix_status	infix_reverse_create_callback (infix_reverse_t **, const char *, void *, infix_registry_t *)
	Creates a type-safe reverse trampoline (callback).
c23_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.
c23_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.
c23_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.
c23_nodiscard infix_library_t *	infix_library_open (const char *)
	Opens a dynamic library and returns a handle to it.
void	infix_library_close (infix_library_t *)
	Closes a dynamic library handle.
c23_nodiscard void *	infix_library_get_symbol (infix_library_t *, const char *)
	Retrieves the address of a symbol (function or variable) from a loaded library.
c23_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.
c23_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.
c23_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.
c23_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.
c23_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.
c23_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.
void	infix_forward_destroy (infix_forward_t *)
	Destroys a forward trampoline and frees all associated memory.
void	infix_reverse_destroy (infix_reverse_t *)
	Destroys a reverse trampoline and frees all associated memory.
c23_nodiscard infix_type *	infix_type_create_primitive (infix_primitive_type_id)
	Creates a static descriptor for a primitive C type.
c23_nodiscard infix_type *	infix_type_create_pointer (void)
	Creates a static descriptor for a generic pointer (void*).
c23_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.
c23_nodiscard infix_type *	infix_type_create_void (void)
	Creates a static descriptor for the void type.
c23_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.
c23_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.
c23_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.
c23_nodiscard infix_status	infix_type_create_array (infix_arena_t *, infix_type **, infix_type *, size_t)
	Creates a new fixed-size array type.
infix_status	infix_type_create_flexible_array (infix_arena_t *, infix_type **, infix_type *)
	Creates a flexible array member type ([?:type]).
c23_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.
c23_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.
c23_nodiscard infix_status	infix_type_create_complex (infix_arena_t *, infix_type **, infix_type *)
	Creates a new _Complex number type.
c23_nodiscard infix_status	infix_type_create_vector (infix_arena_t *, infix_type **, infix_type *, size_t)
	Creates a new SIMD vector type.
infix_struct_member	infix_type_create_member (const char *, infix_type *, size_t)
	A factory function to create an infix_struct_member.
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.
c23_nodiscard infix_arena_t *	infix_arena_create (size_t)
	Creates a new memory arena.
void	infix_arena_destroy (infix_arena_t *)
	Destroys an arena and frees all memory allocated from it.
c23_nodiscard void *	infix_arena_alloc (infix_arena_t *, size_t, size_t)
	Allocates a block of memory from an arena.
c23_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.
c23_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.
c23_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.
c23_nodiscard infix_unbound_cif_func	infix_forward_get_unbound_code (infix_forward_t *)
	Gets the callable function pointer from an unbound forward trampoline.
c23_nodiscard infix_cif_func	infix_forward_get_code (infix_forward_t *)
	Gets the callable function pointer from a bound forward trampoline.
c23_nodiscard void *	infix_reverse_get_code (const infix_reverse_t *)
	Gets the native, callable C function pointer from a reverse trampoline.
c23_nodiscard void *	infix_reverse_get_user_data (const infix_reverse_t *)
	Gets the user-provided data pointer from a closure context.
c23_nodiscard size_t	infix_forward_get_num_args (const infix_forward_t *)
	Gets the total number of arguments for a forward trampoline.
c23_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.
c23_nodiscard const infix_type *	infix_forward_get_return_type (const infix_forward_t *)
	Gets the return type for a forward trampoline.
c23_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.
c23_nodiscard size_t	infix_reverse_get_num_args (const infix_reverse_t *)
	Gets the total number of arguments for a reverse trampoline.
c23_nodiscard const infix_type *	infix_reverse_get_return_type (const infix_reverse_t *)
	Gets the return type for a reverse trampoline.
c23_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.
c23_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.
c23_nodiscard const char *	infix_type_get_name (const infix_type *)
	Gets the semantic alias of a type, if one exists.
c23_nodiscard infix_type_category	infix_type_get_category (const infix_type *)
	Gets the fundamental category of a type.
c23_nodiscard size_t	infix_type_get_size (const infix_type *)
	Gets the size of a type in bytes.
c23_nodiscard size_t	infix_type_get_alignment (const infix_type *)
	Gets the alignment requirement of a type in bytes.
c23_nodiscard size_t	infix_type_get_member_count (const infix_type *)
	Gets the number of members in a struct or union type.
c23_nodiscard const infix_struct_member *	infix_type_get_member (const infix_type *, size_t)
	Gets a specific member from a struct or union type.
c23_nodiscard const char *	infix_type_get_arg_name (const infix_type *, size_t)
	Gets the name of a specific argument from a function type.
c23_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_error_details_t	infix_get_last_error (void)
	Retrieves detailed information about the last error that occurred on the current thread.
c23_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.
c23_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