ffi

func CallFunction ¶

func CallFunction(
	cif *types.CallInterface,
	fn unsafe.Pointer,
	rvalue unsafe.Pointer,
	avalue []unsafe.Pointer,
) (syscall.Errno, error)

CallFunction executes a C function call without context support.

This is equivalent to CallFunctionContext(context.Background(), cif, fn, rvalue, avalue). For operations that need cancellation or timeout control, use CallFunctionContext instead.

errno is captured inside the assembly trampoline immediately after the C function returns, before the Go runtime can migrate the goroutine to a different OS thread. On Windows, errno is always 0.

Parameters:

• cif: Prepared call interface (from PrepareCallInterface)
• fn: Function pointer obtained from GetSymbol (must not be nil)
• rvalue: Pointer to buffer for return value (can be nil for void functions)
• avalue: Slice of pointers to argument values, one per argument type of cif

Returns:

• errno: C errno captured after the call (0 on success or Windows)
• err: nil on success; *InvalidCallInterfaceError if cif, fn or cif.ReturnType is nil, len(avalue) differs from the number of argument types, or a struct result of a CallInterface not filled by PrepareCallInterface has no Size or Alignment

Example:

// Calling open(2) and checking errno on failure:
errno, err := ffi.CallFunction(
    &cif,
    openFn,
    unsafe.Pointer(&result),
    []unsafe.Pointer{unsafe.Pointer(&pathPtr), unsafe.Pointer(&flags)},
)
if result == -1 {
    log.Printf("open failed: %v", errno)
}

// When errno is not needed:
_, err := ffi.CallFunction(&cif, strlenFn, unsafe.Pointer(&result), avalue)

For context-aware calls with timeout support, see CallFunctionContext.

func CallFunctionContext ¶

func CallFunctionContext(
	ctx context.Context,
	cif *types.CallInterface,
	fn unsafe.Pointer,
	rvalue unsafe.Pointer,
	avalue []unsafe.Pointer,
) (syscall.Errno, error)

CallFunctionContext executes a C function call with context support.

This function performs the actual FFI call to the C function, handling all platform-specific calling convention details automatically. It checks the context before executing to prevent starting expensive operations when the context is already cancelled or has exceeded its deadline.

errno is captured inside the assembly trampoline immediately after the C function returns, before the Go runtime can migrate the goroutine to a different OS thread. On Windows, errno is always 0 (use syscall.GetLastError() for Win32 error codes).

Parameters:

• ctx: Context for cancellation and timeout control (use context.Background() if not needed)
• cif: Prepared call interface (from PrepareCallInterface)
• fn: Function pointer obtained from GetSymbol (must not be nil)
• rvalue: Pointer to buffer for return value (can be nil for void functions)
• avalue: Slice of pointers to argument values, one per argument type of cif

Returns:

• errno: C errno captured after the call (0 on success or Windows)
• err: nil on success; ctx.Err() if context cancelled; *InvalidCallInterfaceError if cif, fn or cif.ReturnType is nil, len(avalue) differs from the number of argument types, or a struct result of a CallInterface not filled by PrepareCallInterface has no Size or Alignment

Example:

// Call with timeout
ctx, cancel := context.WithTimeout(context.Background(), 100*time.Millisecond)
defer cancel()

var result float64
arg := 16.0
errno, err := ffi.CallFunctionContext(
    ctx,
    &cif,
    sqrtPtr,
    unsafe.Pointer(&result),
    []unsafe.Pointer{unsafe.Pointer(&arg)},
)
if err == context.DeadlineExceeded {
    log.Println("Call timed out")
}

Note:

• Context cancellation check occurs BEFORE the call to prevent starting expensive operations when the context is already cancelled.
• Once the C function starts executing, it CANNOT be interrupted mid-flight.
• For cancellable operations, the C library itself must support cancellation.

avalue Convention (critical for correctness) ¶

Each avalue[i] is a pointer TO the argument value, following the libffi convention. GoFFI dereferences avalue[i] to read the value passed to the C function:

Input scalar (int x):       avalue[i] = unsafe.Pointer(&x)
Input pointer (char *buf):  avalue[i] = unsafe.Pointer(&buf)  // GoFFI reads buf → C gets buf
Out-pointer (int *result):  avalue[i] = unsafe.Pointer(&resultPtr)
                            where resultPtr = unsafe.Pointer(&result)

The out-pointer case requires an intermediate variable. Without it, GoFFI reads the VALUE of result (likely 0) instead of its ADDRESS, and the C function receives NULL:

// WRONG — C receives NULL:
var handle unsafe.Pointer
avalue := []unsafe.Pointer{unsafe.Pointer(&handle)}  // GoFFI reads handle (nil)

// CORRECT — C receives &handle:
var handle unsafe.Pointer
handlePtr := unsafe.Pointer(&handle)
avalue := []unsafe.Pointer{unsafe.Pointer(&handlePtr)}  // GoFFI reads handlePtr (&handle)

Safety:

• All argument pointers must remain valid during the call
• Hold pointer arguments in unsafe.Pointer (or *T) variables, never uintptr, all the way from where the address is taken to avalue. That includes the parameters of your own binding wrappers: a wrapper such as func MapMemory(..., ppData uintptr) loses the pointer even when the caller writes uintptr(unsafe.Pointer(&local)) in its argument list. The compiler keeps a uintptr's target alive and unmoved only in the argument list of a call to a function implemented in assembly or marked //go:uintptrescapes (package unsafe, rule (4)); CallFunction and your wrapper are ordinary Go functions. A local reachable only through a uintptr stays on the goroutine stack, the stack can move before the C function runs, and C then reads or writes the old address.
• Memory reachable from rvalue and avalue through pointer-typed values is kept alive and in place for the call: CallFunction lets avalue escape, so such memory is allocated on the heap, which the GC does not move.
• If C keeps a pointer to Go memory after the call returns, or reads it from a uintptr-typed C struct field or an out-parameter slot that must stay uintptr, pin it with runtime.Pinner for as long as C uses it, or use memory allocated by C
• Return value buffer must be large enough for the result type
• Use runtime.KeepAlive() if needed to prevent premature GC of arguments

func FreeLibrary ¶

func FreeLibrary(handle unsafe.Pointer) error

FreeLibrary unloads a previously loaded library using dlclose.

This function decrements the reference count of the loaded library. When the reference count reaches zero, the library is unloaded from memory.

Parameters:

• handle: Library handle from LoadLibrary (can be nil)

Returns:

• nil on success
• Error if the library could not be unloaded

Example:

handle, err := ffi.LoadLibrary("libm.so.6")
if err != nil {
    log.Fatal(err)
}
defer ffi.FreeLibrary(handle)

Safety:

• Do not use function pointers obtained from this library after FreeLibrary
• Always pair LoadLibrary with FreeLibrary to prevent resource leaks
• Safe to call with nil handle (returns nil without error)

func GetSymbol ¶

func GetSymbol(handle unsafe.Pointer, name string) (unsafe.Pointer, error)

GetSymbol retrieves a function pointer from a loaded library using dlsym.

This function looks up a symbol (function or variable) in the loaded library and returns its address for use with CallFunction.

Parameters:

• handle: Library handle from LoadLibrary
• name: Name of the symbol to retrieve (e.g., "sqrt", "glClear")

Returns:

• Function pointer (use with CallFunction)
• Error if symbol not found or lookup fails

Example:

sqrtPtr, err := ffi.GetSymbol(handle, "sqrt")
if err != nil {
    log.Fatal(err)
}

Note: The returned pointer is only valid while the library remains loaded.

func LoadLibrary ¶

func LoadLibrary(name string) (unsafe.Pointer, error)

LoadLibrary loads a shared library using dlopen.

This function loads the specified shared library and returns a handle for use with GetSymbol. The library is loaded with RTLD_NOW|RTLD_GLOBAL flags.

Parameters:

• name: Path to the shared library (e.g., "libm.so.6", "/usr/lib/libGL.so.1")

Returns:

• Handle to the loaded library (use with GetSymbol and FreeLibrary)
• Error if loading fails

Example:

handle, err := ffi.LoadLibrary("libm.so.6")
if err != nil {
    log.Fatal(err)
}
defer ffi.FreeLibrary(handle)

Note: Always pair LoadLibrary with FreeLibrary to prevent resource leaks.

func NewCallback ¶ added in v0.2.0

func NewCallback(fn any) uintptr

NewCallback registers a Go function as a C callback and returns a function pointer. The returned uintptr can be passed to C code as a callback function pointer.

Requirements:

• fn must be a function (not nil)
• fn can have multiple arguments of basic types (int, float, pointer, etc.)
• fn can return at most one value of basic type
• Complex types (string, slice, map, chan, interface) are not supported
• Maximum 2000 callbacks can be registered (program lifetime limit)

Memory Management:

• Callbacks are never freed (stored in global registry)
• This prevents GC from collecting callback data while C code uses it
• For applications with dynamic callback creation, consider callback pools

Usage Example:

func myCallback(x int, y float64) int {
    return x + int(y)
}

callbackPtr := ffi.NewCallback(myCallback)
// Pass callbackPtr to C code as function pointer

Using unsafe.Pointer is necessary here as we're creating a function pointer that C code can call. The pointer is obtained from the assembly trampoline table and is guaranteed to be valid for the program lifetime.

func PrepareCallInterface ¶

func PrepareCallInterface(
	cif *types.CallInterface,
	convention types.CallingConvention,
	returnType *types.TypeDescriptor,
	argTypes []*types.TypeDescriptor,
) error

PrepareCallInterface prepares a function call interface for calling a C function.

This function initializes the CallInterface structure with the necessary metadata for making FFI calls. It must be called before CallFunction.

Parameters:

• cif: Pointer to CallInterface structure to initialize (must not be nil)
• convention: Calling convention (types.DefaultCall, types.CDecl, types.StdCall, etc.)
• returnType: Type descriptor for return value (use types.VoidTypeDescriptor for void)
• argTypes: Slice of type descriptors for each argument (nil or empty slice for no arguments)

Returns:

• nil on success
• ErrInvalidCallInterface if parameters are invalid
• Other errors if type validation or platform preparation fails

Example:

var cif types.CallInterface
err := ffi.PrepareCallInterface(
    &cif,
    types.DefaultCall,
    types.Int32TypeDescriptor,
    []*types.TypeDescriptor{
        types.PointerTypeDescriptor,
        types.Int32TypeDescriptor,
    },
)

For functions with no arguments, pass nil or an empty slice for argTypes:

err := ffi.PrepareCallInterface(&cif, types.DefaultCall, types.VoidTypeDescriptor, nil)

func PrepareVariadicCallInterface ¶ added in v0.5.2

func PrepareVariadicCallInterface(
	cif *types.CallInterface,
	convention types.CallingConvention,
	nfixedargs int,
	returnType *types.TypeDescriptor,
	argTypes []*types.TypeDescriptor,
) error

PrepareVariadicCallInterface prepares a call interface for a C variadic function.

nfixedargs is the count of fixed parameters before '...' in the C prototype. argTypes must contain ALL arguments (fixed + variadic) for this specific call. A new CIF must be prepared for each unique combination of variadic argument types.

On Apple ARM64, variadic arguments are forced to the stack per Apple's AAPCS64 extension. The register allocators are exhausted at the fixed/variadic boundary so that variadic arguments land on the stack even when registers are available. On all other platforms, this function behaves identically to PrepareCallInterface.

Example:

// Prepare for: int64_t sum_variadic(int64_t count, ...)
// Called with count=3 and three int64_t variadic args.
var cif types.CallInterface
err := ffi.PrepareVariadicCallInterface(
    &cif,
    types.DefaultCall,
    1, // nfixedargs: only 'count' is fixed
    types.SInt64TypeDescriptor,
    []*types.TypeDescriptor{
        types.SInt64TypeDescriptor, // count
        types.SInt64TypeDescriptor, // arg1 (variadic)
        types.SInt64TypeDescriptor, // arg2 (variadic)
        types.SInt64TypeDescriptor, // arg3 (variadic)
    },
)