Top Description Fields Constructors Methods
org.lwjgl.system.libffi

public Class LibFFI

extends Object
Class Inheritance
Imports
javax.annotation.*, java.nio.*, org.lwjgl.*, org.lwjgl.system.*
Native bindings to the libffi library.

The foreign function interface provides a mechanism by which a function can generate a call to another function at runtime without requiring knowledge of the called function's interface at compile time. This enables use of native libraries that LWJGL does not provide bindings for.

libffi assumes that you have a pointer to the function you wish to call and that you know the number and types of arguments to pass it, as well as the return type of the function.

The first thing you must do is create an FFICIF object that matches the signature of the function you wish to call. This is a separate step because it is common to make multiple calls using a single FFICIF. The cif in ffi_cif stands for Call InterFace. To prepare a call interface object, use the function prep_cif. To call a function using an initialized ffi_cif, use the call function.

Field Summary

Modifier and TypeField and Description
public static final int
FFI_BAD_ABI

Status codes.

public static final int
FFI_BAD_ARGTYPE

Status codes.

public static final int
FFI_BAD_TYPEDEF

Status codes.

public static final int
FFI_DEFAULT_ABI

ABI enumeration.

public static final int
FFI_EFI64

ABI enumeration.

public static final int
FFI_FASTCALL

ABI enumeration.

public static final int
FFI_FIRST_ABI

ABI enumeration.

public static final int
FFI_GNUW64

ABI enumeration.

public static final int
FFI_LAST_ABI

ABI enumeration.

public static final int
FFI_MS_CDECL

ABI enumeration.

public static final int
FFI_OK

Status codes.

public static final int
FFI_PASCAL

ABI enumeration.

public static final int
FFI_REGISTER

ABI enumeration.

public static final int
FFI_STDCALL

ABI enumeration.

public static final int
FFI_SYSV

ABI enumeration.

public static final int
FFI_THISCALL

ABI enumeration.

public static final short
FFI_TYPE_DOUBLE

Types used to create custom FFICIF.

public static final FFIType
ffi_type_double

The ffi_type_double struct.

public static final short
FFI_TYPE_FLOAT

Types used to create custom FFICIF.

public static final FFIType
ffi_type_float

The ffi_type_float struct.

public static final short
FFI_TYPE_INT

Types used to create custom FFICIF.

public static final short
FFI_TYPE_LONGDOUBLE

Types used to create custom FFICIF.

public static final FFIType
ffi_type_longdouble

The ffi_type_longdouble struct.

public static final short
FFI_TYPE_POINTER

Types used to create custom FFICIF.

public static final FFIType
ffi_type_pointer

The ffi_type_pointer struct.

public static final FFIType
ffi_type_schar

The ffi_type_schar struct.

public static final FFIType
ffi_type_sint

The ffi_type_sint struct.

public static final short
FFI_TYPE_SINT16

Types used to create custom FFICIF.

public static final FFIType
ffi_type_sint16

The ffi_type_sint16 struct.

public static final short
FFI_TYPE_SINT32

Types used to create custom FFICIF.

public static final FFIType
ffi_type_sint32

The ffi_type_sint32 struct.

public static final short
FFI_TYPE_SINT64

Types used to create custom FFICIF.

public static final FFIType
ffi_type_sint64

The ffi_type_sint64 struct.

public static final short
FFI_TYPE_SINT8

Types used to create custom FFICIF.

public static final FFIType
ffi_type_sint8

The ffi_type_sint8 struct.

public static final FFIType
ffi_type_slong

The ffi_type_slong struct.

public static final FFIType
ffi_type_sshort

The ffi_type_sshort struct.

public static final short
FFI_TYPE_STRUCT

Types used to create custom FFICIF.

public static final FFIType
ffi_type_uchar

The ffi_type_uchar struct.

public static final FFIType
ffi_type_uint

The ffi_type_uint struct.

public static final short
FFI_TYPE_UINT16

Types used to create custom FFICIF.

public static final FFIType
ffi_type_uint16

The ffi_type_uint16 struct.

public static final short
FFI_TYPE_UINT32

Types used to create custom FFICIF.

public static final FFIType
ffi_type_uint32

The ffi_type_uint32 struct.

public static final short
FFI_TYPE_UINT64

Types used to create custom FFICIF.

public static final FFIType
ffi_type_uint64

The ffi_type_uint64 struct.

public static final short
FFI_TYPE_UINT8

Types used to create custom FFICIF.

public static final FFIType
ffi_type_uint8

The ffi_type_uint8 struct.

public static final FFIType
ffi_type_ulong

The ffi_type_ulong struct.

public static final FFIType
ffi_type_ushort

The ffi_type_ushort struct.

public static final short
FFI_TYPE_VOID

Types used to create custom FFICIF.

public static final FFIType
ffi_type_void

The ffi_type_void struct.

public static final int
FFI_UNIX64

ABI enumeration.

public static final int
FFI_VFP

ABI enumeration.

public static final int
FFI_WIN64

ABI enumeration.

Constructor Summary

AccessConstructor and Description
protected
LibFFI()

Method Summary

Modifier and TypeMethod and Description
public static void
ffi_call(FFICIF
a FFICIF structure. It must be initialized with prep_cif or prep_cif_var before it is used with ffi_call.
cif, long
the function to call
fn, ByteBuffer
a pointer to a chunk of memory that will hold the result of the function call.

This must be large enough to hold the result, no smaller than the system register size (generally 32 or 64 bits), and must be suitably aligned; it is the caller's responsibility to ensure this. If CIF declares that the function returns void (using type_void), then rvalue is ignored.

In most situations, libffi will handle promotion according to the ABI. However, for historical reasons, there is a special case with return values that must be handled by your code. In particular, for integral (not struct) types that are narrower than the system register size, the return value will be widened by libffi. libffi provides a type, ffi_arg, that can be used as the return type. For example, if the CIF was defined with a return type of char, libffi will try to store a full ffi_arg into the return value.

rvalue, PointerBuffer
a vector of void * pointers that point to the memory locations holding the argument values for a call.

If cif declares that the function has no arguments (i.e., nargs was 0), then avalues is ignored. Note that argument values may be modified by the callee (for instance, structs passed by value); the burden of copying pass-by-value arguments is placed on the caller.

Note that while the return value must be register-sized, arguments should exactly match their declared type. For example, if an argument is a short, then the entry in avalues should point to an object declared as short; but if the return type is short, then rvalue should point to an object declared as a larger type - usually ffi_arg.

avalues)

Calls the function fn according to the description given in cif.

public static FFIClosure

Returns:

a pointer to the writable address
ffi_closure_alloc(long
the number of bytes to allocate. Should be sufficient to hold an ffi_closure object (FFIClosure#SIZEOF).
size, PointerBuffer
a buffer in which to place the returned executable address
code)

Allocates a chunk of memory holding size bytes.

public static void
ffi_closure_free(FFIClosure
the address of an FFIClosure structure
writable)

Frees memory allocated using closure_alloc.

private static native int
FFI_DEFAULT_ABI()

private static native int
FFI_EFI64()

private static native int
FFI_FASTCALL()

private static native int
FFI_FIRST_ABI()

public static int

Returns:

returns OK on success; BAD_ABI if abi is invalid; or BAD_TYPEDEF if struct_type is invalid in some way. Note that only FFI_STRUCT types are valid here.
ffi_get_struct_offsets(int
the ABI to use; this is needed because in some cases the layout depends on the ABI
abi, FFIType struct_type, PointerBuffer
an out parameter. The caller is responsible for providing enough space for all the results to be written - one element per element type in struct_type. If offsets is NULL, then the type will be laid out but not otherwise modified. This can be useful for accessing the type's size or layout.
offsets)

Computes the offset of each element of the given structure type.

private static native int
FFI_GNUW64()

private static native int
FFI_LAST_ABI()

private static native int
FFI_MS_CDECL()

private static native int
FFI_PASCAL()

public static int

Returns:

a status code, of type ffi_status.

This will be either OK if everything worked properly; BAD_TYPEDEF if one of the ffi_type objects is incorrect; or BAD_ABI if the ABI parameter is invalid.

ffi_prep_cif(FFICIF
the ffi_cif structure to prepare
cif, int
the ABI to use; normally DEFAULT_ABI is what you want. One of:
FIRST_ABIWIN64GNUW64UNIX64EFI64SYSVSTDCALLTHISCALLFASTCALLMS_CDECLPASCAL
REGISTERVFPLAST_ABIDEFAULT_ABI
abi, FFIType
a pointer to an ffi_type structure that describes the return type of the function
rtype, PointerBuffer
a vector of ffi_type pointers. atypes must have nargs elements. If nargs is 0, this argument is ignored.
atypes)

Initializes the specified Call Interface (CIF) according to the given parameters.

public static int

Returns:

a status code, of type ffi_status.

This will be either OK if everything worked properly; BAD_TYPEDEF if one of the ffi_type objects is incorrect; or BAD_ABI if the ABI parameter is invalid.

ffi_prep_cif_var(FFICIF
the ffi_cif structure to prepare
cif, int
the ABI to use; normally DEFAULT_ABI is what you want. One of:
FIRST_ABIWIN64GNUW64UNIX64EFI64SYSVSTDCALLTHISCALLFASTCALLMS_CDECLPASCAL
REGISTERVFPLAST_ABIDEFAULT_ABI
abi, int
the number of fixed arguments, prior to any variadic arguments. It must be greater than zero.
nfixedargs, FFIType
a pointer to an ffi_type structure that describes the return type of the function
rtype, PointerBuffer
a vector of ffi_type pointers. atypes must have ntotalargs elements.
atypes)

Initializes the specified Call Interface (CIF) according to the given parameters for a call to a variadic function.

public static int

Returns:

OK if everything went ok, and one of the other ffi_status values on error
ffi_prep_closure_loc(FFIClosure
the address of an ffi_closure object; this is the writable address returned by closure_alloc.
closure, FFICIF
the ffi_cif describing the function parameters
cif, long
the function which will be called when the closure is invoked. It is called with the arguments:
  • cif - The ffi_cif passed to ffi_prep_closure_loc.
  • ret - a pointer to the memory used for the function's return value.

    If the function is declared as returning void, then this value is garbage and should not be used.

    Otherwise, fun must fill the object to which this points, following the same special promotion behavior as ffi_call. That is, in most cases, ret points to an object of exactly the size of the type specified when cif was constructed. However, integral types narrower than the system register size are widened. In these cases your program may assume that ret points to an ffi_arg object.

  • args - a vector of pointers to memory holding the arguments to the function.
  • user_data - the same USER_DATA that was passed to ffi_prep_closure_loc.
fun, long
an arbitrary datum that is passed, uninterpreted, to your closure function
user_data, long
the executable address returned by closure_alloc.
codeloc)

Prepares a closure function.

private static native int
FFI_REGISTER()

private static native int
FFI_STDCALL()

private static native int
FFI_SYSV()

private static native int
FFI_THISCALL()

private static native short
FFI_TYPE_DOUBLE()

The double type.

private static FFIType
ffi_type_double()

private static FFIType
ffi_type_float()

private static FFIType
ffi_type_longdouble()

private static FFIType
ffi_type_pointer()

private static FFIType
ffi_type_schar()

private static FFIType
ffi_type_sint()

private static FFIType
ffi_type_sint16()

private static FFIType
ffi_type_sint32()

private static FFIType
ffi_type_sint64()

private static FFIType
ffi_type_sint8()

private static FFIType
ffi_type_slong()

private static FFIType
ffi_type_sshort()

private static FFIType
ffi_type_uchar()

private static FFIType
ffi_type_uint()

private static FFIType
ffi_type_uint16()

private static FFIType
ffi_type_uint32()

private static FFIType
ffi_type_uint64()

private static FFIType
ffi_type_uint8()

private static FFIType
ffi_type_ulong()

private static FFIType
ffi_type_ushort()

private static FFIType
ffi_type_void()

private static native int
FFI_UNIX64()

private static native int
FFI_VFP()

private static native int
FFI_WIN64()

public static native void
nffi_call(long cif, long fn, long rvalue, long avalues)

Unsafe version of: call

public static native long
nffi_closure_alloc(long size, long code)

Unsafe version of: closure_alloc

public static native void
nffi_closure_free(long writable)

Unsafe version of: closure_free

public static native int
nffi_get_struct_offsets(int abi, long struct_type, long offsets)

Unsafe version of: get_struct_offsets

public static native int
nffi_prep_cif(long cif, int abi, int
the number of arguments that this function accepts
nargs, long rtype, long atypes)

Unsafe version of: prep_cif

public static native int
nffi_prep_cif_var(long cif, int abi, int nfixedargs, int
the total number of arguments, including variadic and fixed arguments
ntotalargs, long rtype, long atypes)

Unsafe version of: prep_cif_var

public static native int
nffi_prep_closure_loc(long closure, long cif, long fun, long user_data, long codeloc)

Unsafe version of: prep_closure_loc

private static native long
nffi_type_double()

private static native long
nffi_type_float()

private static native long
nffi_type_longdouble()

private static native long
nffi_type_pointer()

private static native long
nffi_type_schar()

private static native long
nffi_type_sint()

private static native long
nffi_type_sint16()

private static native long
nffi_type_sint32()

private static native long
nffi_type_sint64()

private static native long
nffi_type_sint8()

private static native long
nffi_type_slong()

private static native long
nffi_type_sshort()

private static native long
nffi_type_uchar()

private static native long
nffi_type_uint()

private static native long
nffi_type_uint16()

private static native long
nffi_type_uint32()

private static native long
nffi_type_uint64()

private static native long
nffi_type_uint8()

private static native long
nffi_type_ulong()

private static native long
nffi_type_ushort()

private static native long
nffi_type_void()

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait