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...

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.

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.
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.
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.

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