ffi

func CallFunction ¶

func CallFunction(
	cif *types.CallInterface,
	fn unsafe.Pointer,
	rvalue unsafe.Pointer,
	avalue []unsafe.Pointer,
) 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.

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 (length must match argCount from PrepareCallInterface)

Returns:

• nil on success
• ErrInvalidCallInterface if cif or fn is nil
• ErrFunctionCallFailed if the call execution fails

Example:

// Calling strlen(const char *str)
var result uintptr
str := "Hello"
err := ffi.CallFunction(
    &cif,
    strlenPtr,
    unsafe.Pointer(&result),
    []unsafe.Pointer{unsafe.Pointer(&str)},
)

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

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 (length must match argCount from PrepareCallInterface)

Returns:

• nil on success
• ctx.Err() if context is cancelled or deadline exceeded before call starts
• ErrInvalidCallInterface if cif or fn is nil
• ErrFunctionCallFailed if the call execution fails

Example:

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

var result float64
arg := 16.0
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.

Safety:

• All argument pointers must remain valid during the call
• 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)