libffi and the runtime calling convention bridge
A portable foreign-function interface library.
At a glance
- What is it?
- libffi lets a program call a compiled function when the argument types are only known at run time. It stops at the machine layer on purpose, and everything above it is somebody else's problem.
- Who is it for?
- Adopt libffi when you are writing an interpreter, a binding layer or anything else that must dispatch to compiled code with types decided at run time, and you already have a layer above it to handle conversions. Do not adopt it to bridge two managed languages directly, or to save writing a marshaller you will own forever.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly C, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 14, 2026, and from our analysis. They are not legal advice.
Star history
- libffi/libffi4,407 ★ · +29
| Repository | 2026-09-23 | 2026-11-14 |
|---|---|---|
| libffi/libffi | 4.4k | 4.4k |
29 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The compile-time assumption libffi exists to break
A compiler emitting a call has to decide, before it ever reaches your source line, which registers and stack slots hold each argument and where the return value lands. Those decisions are the calling convention, and separate compilation depends on both sides agreeing on them. The agreement is normally invisible, because it is baked in by the compiler at the moment it translates a declaration.
That assumption breaks in one specific situation. An interpreter is told at run time that the function it is about to invoke takes three arguments, two of them integers and one a pointer. Nothing in the interpreter's own compiled code was generated for that shape. Without help, it has no way to know whether the third argument belongs in a register or on the stack.
libffi's answer is to move that decision into a library that can inspect a description at run time and then perform the call using the target platform's convention. The reader who should care most is anyone writing an interpreter, a language runtime, or a binding generator that has to hand control to code it did not compile. A program that knows its argument types when it compiles has no use for any of this.
The call interface description is the whole public surface
The interface libffi exposes is deliberately narrow: a description of the call, prepared once, then used to invoke a function pointer. Nothing in the description carries semantics. It says how many values are involved, what their types are, and where the return value goes. It does not say what those values mean.
That boundary is the reason libffi is small and also the reason using it directly is unpleasant. The library hands you a working ABI-level invocation and stops. Anything above it, the layer that decides whether that integer is a file descriptor, a length, or a pointer to a string, is outside its scope by design.
The practical consequence shows up in every direct consumer. The library is a set of headers plus a small amount of machine-specific code, not a framework with a configuration model. There is no plugin registry, no resolver, no callback queue. If you want one of those, you write it, and every project that wraps libffi ends up writing a slightly different version of the same thing. That duplication is the single biggest reason a higher-level binding library exists rather than everyone calling libffi directly.
The type conversion layer the README deliberately assigns to somebody else
The README is unusually direct about the division of labour. It states that a layer must exist above libffi that handles type conversions for values passed between two languages, and that libffi really only provides the lowest, machine dependent layer of a fully featured foreign function interface.
Read that as a warning to anyone arriving from the phrase foreign function interface. The common meaning of an FFI covers object layout, string encoding, ownership, error propagation, reference counting, and lifetime rules for anything allocated on one side and handed to the other. libffi supplies none of those. It will happily place a pointer into a register for you, and it has no opinion about who frees it.
There is a second, subtler trap. Value conversion is not only about user-defined types. Every platform disagrees about whether a 64-bit float goes in an SSE register or a general purpose one, whether integers are sign extended or zero extended, and where a variadic function's floating point arguments live. Where libffi has been ported, that disagreement is handled in the machine layer rather than by you. Where the port is thin, the caller inherits whatever the platform does. Getting this wrong does not produce a clean error. It produces wrong numbers, which is the worst kind of bug to debug.
The platform table lists what was tested, not what is supported
The README qualifies its own support list before you read a single row. It says that at the time of release the configurations shown have been tested, and calls them basic configurations. That word choice is doing real work. The table is not a support promise, and a row's presence tells you a build existed for that pairing, not that edge cases in your toolchain are handled.
The list itself is the argument for the library. AArch64 on Linux with GCC, x86 and x86-64 across Linux, MinGW, Cygwin and Solaris, RISC-V 32-bit and 64-bit, LoongArch32 and LoongArch64, S390X, SPARC64, and PowerPC in both 32-bit and 64-bit form appear alongside Windows targets built with MSVC and WASM32 and WASM64 built with Emscripten. Anything with an ABI worth naming is represented.
Then the tail of the table gets interesting. Moxie on bare metal, X86 on Interix, M88K on OpenBSD/mvme88k, VAX, Blackfin on uClinux, M68K on RTEMS and FreeMiNT, HPPA on HPUX. A bare-metal row is a genuine data point about how low-level the abstraction goes, since there is no operating system underneath to supply a stack convention. It is also a reminder that ports outlive the platforms their users actually run. Check that your row is present, and check the compiler column too, since the Solaris and AIX rows pair GCC with vendor compilers in ways that can change register allocation rules.
Four build systems sit side by side in the repository root
The top-level layout tells you the project serves four different toolchains from one tree. There is autogen.sh alongside configure.ac, configure.host and Makefile.am for the autotools path, and acinclude.m4 holding the project's own macro logic. There is libffi.xcodeproj for Apple toolchains, and a matching generate-darwin-source-and-headers.py at the root, for generating Darwin sources and headers.
Then there is msvc_build, with an msvcc.sh driver for MSVC at the root. The presence of three support scripts is the detail worth pausing on. libtool-ldflags, libtool-version and libffi.map.in exist to control what ends up in the shared library and what symbols leave it, which matters when several processes or several versions of a language runtime load the library into one address space. make_sunver.pl sits alongside them, generating the version script for Solaris.
The homepage given in the repository is the place the project points for obtaining the source, and the distribution packages named in common use, such as the dev and so variants that turn up under this project's name, come from your operating system vendor rather than from the project itself.
What the README leaves out, and where callers break
The gap that matters most is between a successful call and a correct program. libffi performs the invocation. It does not check that the argument count you described matches what the target function actually expects, that a pointer you passed stays alive for the duration of the call, or that the return value matches the type you declared in the description. A mismatch between the description and the real function signature is undefined behaviour, and the symptom on most platforms is a corrupted stack rather than a signal.
The second gap is thread and signal safety of the caller, not the library. If two threads build descriptions over shared state, or a call happens while a signal handler inspects the same buffers, nothing in the interface described here arbitrates it. Treat a prepared description as immutable once published.
The third gap is upgrade cadence. Releases landed in quick succession, with 3.7.0 and 3.7.1 in July 2026 and 3.8.0 in August 2026, and the last push to the repository was on 2026-10-28, so the tree is receiving changes. The repository carries both LICENSE and LICENSE-BUILDTOOLS, which suggests the build tooling is licensed separately from the library source. That distinction matters for distributors who redistribute the built artifacts, and it is a packaging question to resolve with your own legal review rather than an engineering one.
Two ways to reach a C function, and which one libffi is
There are two broad approaches to calling compiled code from a managed language, and they differ in when the marshalling decision is made. Compile-time binding parses C declarations and generates a wrapper in the host language, then compiles that wrapper to machine code. The calling convention is baked into generated code ahead of time, exactly like a compiler would do. The cost is a build step and a code generator that must handle every declaration you want to expose.
Runtime binding keeps the dispatch decision in a library that receives a description and performs the call on the spot. That is libffi's approach, and it is why it exists: no generated code, no ahead-of-time step, and argument types can vary from call to call within the same program. The cost is that every conversion, every ownership rule and every error path is now runtime logic you own.
Python's ctypes sits on the runtime side and is built on this library. Contrast that with a compile-time binding such as CFFI's API mode, where the decision moves earlier and the runtime cost drops. If your call sites have a fixed, known shape, you are paying runtime dispatch for something that could have been resolved when the code was built. If the shape is genuinely dynamic, no amount of code generation removes the problem, and libffi is the layer that stays.
Editorial conclusion
Adopt libffi when you are writing an interpreter, a binding layer or anything else that must dispatch to compiled code with types decided at run time, and you already have a layer above it to handle conversions. Do not adopt it to bridge two managed languages directly, or to save writing a marshaller you will own forever. Before anything else, open the tested-platform table and confirm your architecture and compiler pair is in it, because the README describes those rows as basic configurations rather than as a support guarantee.
Frequently asked questions
What does libffi do?
It provides a portable, high level programming interface to various calling conventions, so a program can call any function given a call interface description at run time rather than at compile time.
How do I use libffi?
You build a call interface description for the argument types and return type, prepare it, then use it to invoke a function pointer. The README states that a layer handling type conversions must exist above libffi.
How do I install libffi on Ubuntu?
The repository's homepage is sourceware.org/libffi, and the repository ships autogen.sh, configure.ac, an Xcode project and msvc_build for building it.
Is libffi itself a complete foreign function interface?
No. The README says libffi really only provides the lowest, machine dependent layer, and that a layer must exist above it to handle type conversions for values passed between two languages.
What is libffi used for?
Programs that cannot know their argument types at compile time, such as an interpreter told at run time the number and types of arguments used to call a given function, use it as a bridge to compiled code.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/libffi-libffi)Star history chart for your README
[](https://hysenlabs.com/projects/libffi-libffi)Was this useful?