infix: A JIT-powered FFI library for C

infix is a modern, lightweight C library that lets you call any C function or create C callbacks at runtime, using simple, human-readable strings to describe the function's signature.

It's designed to be the simplest way to add a dynamic Foreign Function Interface (FFI) to your project, whether you're building a language runtime, a plugin system, or just need to call functions from a dynamically loaded library.

Key Features

• Human-Readable Signatures: Describe complex C functions with an intuitive string format (e.g., "({double, double}, int) -> *char").
• Forward & Reverse Calls: Call C functions ("forward") and create C function pointers that call back into your code ("reverse").
• Simple Integration: Add a single C file and a header directory to your project to get started. No complex dependencies.
• Type Registry: Define, reuse, and link complex, recursive, and mutually-dependent structs by name.
• Security-First Design: Hardened against vulnerabilities with Write XOR Execute (W^X) memory, guard pages, and fuzz testing.
• High Performance: A Just-in-Time (JIT) compiler generates optimized machine code trampolines, making calls nearly as fast as a direct C call after the initial setup.

Full Documentation

• Installation Guide: How to build and integrate infix.
• API Quick Reference: A complete reference for the public API.
• The FFI Cookbook: Practical, real-world examples and recipes.
• Signature Language Reference: A deep dive into the signature string format.
• Porting Guide: Instructions for adding support for a new CPU architecture or ABI.
• Contributing Guide: How to contribute to the project.

---

How It Works: A Quick Example

The heart of infix is its signature string. Here’s how you would call a simple C function:

#include <infix/infix.h>
#include <stdio.h>

// The C function we want to call.
int add(int a, int b) { return a + b; }

int main() {
    // 1. Describe the function's signature as a string.
    const char* signature = "(int, int) -> int";

    // 2. Create a "trampoline"—a JIT-compiled function wrapper.
    infix_forward_t* trampoline = NULL;
    infix_forward_create(&trampoline, signature, (void*)add, NULL);
    infix_cif_func cif = infix_forward_get_code(trampoline);

    // 3. Prepare an array of *pointers* to the arguments.
    int a = 10, b = 32;
    void* args[] = { &a, &b };
    int result;

    // 4. Call the function through the trampoline.
    cif(&result, args);

    printf("Result: %d\n", result); // Output: Result: 42

    // 5. Clean up.
    infix_forward_destroy(trampoline);
    return 0;
}

Creating Callbacks

infix can also generate native C function pointers that call back into your code. This is perfect for interfacing with C libraries that expect callbacks, like qsort.

#include <infix/infix.h>
#include <stdlib.h>

// The C handler function for our callback.
int compare_integers(const void* a, const void* b) {
    return (*(const int*)a - *(const int*)b);
}

void run_qsort_example() {
    // 1. Describe the callback's signature.
    const char* cmp_sig = "(*void, *void) -> int";

    // 2. Create a reverse trampoline.
    infix_reverse_t* context = NULL;
    infix_reverse_create_callback(&context, cmp_sig, (void*)compare_integers, NULL);

    // 3. Get the JIT-compiled C function pointer.
    int (*my_comparator)(const void*, const void*) = infix_reverse_get_code(context);

    // 4. Use the generated callback with the C library function.
    int numbers[] = { 5, 1, 4, 2, 3 };
    qsort(numbers, 5, sizeof(int), my_comparator);
    // `numbers` is now sorted: [1, 2, 3, 4, 5]

    infix_reverse_destroy(context);
}

Getting Started

The easiest way to use infix is to add its source directly to your project.

1. Copy the src/ and include/ directories into your project.
2. Add src/infix.c to your build system's list of source files.
3. Add the include/ directory to your include paths.
4. #include <infix/infix.h> in your code.

For more advanced build options, including building as a standalone library with CMake or xmake, see the Building and Integration Guide.

Project Philosophy

infix is built on three core principles:

1. Security First: An FFI library with a JIT is a prime target for vulnerabilities. We defend against these with a multi-layered approach, including strict W^X memory, hardened integer arithmetic, and continuous fuzz testing.
2. Performance by Design: FFI overhead should be minimal. infix separates the one-time generation cost from the near-zero call-time cost, making it exceptionally fast in high-performance applications when trampolines are cached.
3. Simplicity and Portability: Platform- and ABI-specific logic is strictly isolated, making the library easy to maintain, simple to integrate, and straightforward to port to new architectures.

Platform Support

infix is rigorously tested on a wide array of operating systems, compilers, and architectures with every commit.

OS	Version	Architecture	Compiler	Status
DragonflyBSD	6.4.0	x86-64	GCC
FreeBSD	14.3	x86-64	GCC
	14.3	AArch64	GCC
	14.3	x86-64	Clang
	14.3	AArch64	Clang
macOS	Sequoia	AArch64	Clang
	Sequoia	AArch64	GCC
NetBSD	10.1	AArch64	GCC
	10.1	x86-64	GCC
OmniOS	r151052	x86-64	GCC
OpenBSD	7.7	AArch64	Clang
	7.7	AArch64	GCC
	7.7	x86-64	Clang
	7.7	x86-64	Clang
Solaris	11.4	x86-64	GCC
Ubuntu	24.04	AArch64	Clang
	24.04	AArch64	GCC
	24.04	x86-64	Clang
	24.04	x86-64	GCC
Windows	Server 2025	AArch64	Clang
	Server 2025	AArch64	GCC
	Server 2025	AArch64	MSVC
	Server 2025	x86-64	Clang
	Server 2025	x86-64	GCC
	Server 2025	x86-64	MSVC

In addition to the CI platforms tested here on Github, I can verify infix builds and passes unit tests on Android/Termux.

Licenses

To maximize usability for all, infix is dual-licensed under the Artistic License 2.0 and the MIT License. You may choose to use the code under the terms of either license.

At your discretion, all standalone documentation (.md), explanatory text, Doxygen-style documentation blocks, comments, and code examples contained within this repository may be used, modified, and distributed under the terms of the Creative Commons Attribution 4.0 International License (CC BY 4.0). I encourage you to share and adapt the documentation for any purpose (generating an API reference website, creating tutorials, etc.), as long as you give appropriate credit.