gcc/libffi/man/ffi_call.3

104 lines
2.3 KiB
Groff
Raw Normal View History

.Dd February 15, 2008
.Dt ffi_call 3
.Sh NAME
.Nm ffi_call
.Nd Invoke a foreign function.
.Sh SYNOPSIS
.In ffi.h
.Ft void
.Fo ffi_call
.Fa "ffi_cif *cif"
.Fa "void (*fn)(void)"
.Fa "void *rvalue"
.Fa "void **avalue"
.Fc
.Sh DESCRIPTION
The
.Nm ffi_call
function provides a simple mechanism for invoking a function without
requiring knowledge of the function's interface at compile time.
.Fa fn
is called with the values retrieved from the pointers in the
.Fa avalue
array. The return value from
.Fa fn
is placed in storage pointed to by
.Fa rvalue .
.Fa cif
contains information describing the data types, sizes and alignments of the
arguments to and return value from
.Fa fn ,
and must be initialized with
.Nm ffi_prep_cif
before it is used with
.Nm ffi_call .
.Pp
.Fa rvalue
[multiple changes] 2009-06-12 Andrew Haley <aph@redhat.com> * ChangeLog.libffi: testsuite/libffi.call/cls_align_sint64.c, testsuite/libffi.call/cls_align_uint64.c, testsuite/libffi.call/cls_ulonglong.c, testsuite/libffi.call/return_ll1.c, testsuite/libffi.call/stret_medium2.c: Fix printf format specifiers. testsuite/libffi.special/unwindtest.cc: include stdint.h. 2009-06-11 Timothy Wall <twall@users.sf.net> * Makefile.am, configure.ac, include/ffi.h.in, include/ffi_common.h, src/closures.c, src/dlmalloc.c, src/x86/ffi.c, src/x86/ffitarget.h, src/x86/win64.S (new), README: Added win64 support (mingw or MSVC) * Makefile.in, include/Makefile.in, man/Makefile.in, testsuite/Makefile.in, configure, aclocal.m4: Regenerated * ltcf-c.sh: properly escape cygwin/w32 path * man/ffi_call.3: Clarify size requirements for return value. * src/x86/ffi64.c: Fix filename in comment. * src/x86/win32.S: Remove unused extern. * testsuite/libffi.call/closure_fn0.c, testsuite/libffi.call/closure_fn1.c, testsuite/libffi.call/closure_fn2.c, testsuite/libffi.call/closure_fn3.c, testsuite/libffi.call/closure_fn4.c, testsuite/libffi.call/closure_fn5.c, testsuite/libffi.call/closure_fn6.c, testsuite/libffi.call/closure_stdcall.c, testsuite/libffi.call/cls_12byte.c, testsuite/libffi.call/cls_16byte.c, testsuite/libffi.call/cls_18byte.c, testsuite/libffi.call/cls_19byte.c, testsuite/libffi.call/cls_1_1byte.c, testsuite/libffi.call/cls_20byte.c, testsuite/libffi.call/cls_20byte1.c, testsuite/libffi.call/cls_24byte.c, testsuite/libffi.call/cls_2byte.c, testsuite/libffi.call/cls_3_1byte.c, testsuite/libffi.call/cls_3byte1.c, testsuite/libffi.call/cls_3byte2.c, testsuite/libffi.call/cls_4_1byte.c, testsuite/libffi.call/cls_4byte.c, testsuite/libffi.call/cls_5_1_byte.c, testsuite/libffi.call/cls_5byte.c, testsuite/libffi.call/cls_64byte.c, testsuite/libffi.call/cls_6_1_byte.c, testsuite/libffi.call/cls_6byte.c, testsuite/libffi.call/cls_7_1_byte.c, testsuite/libffi.call/cls_7byte.c, testsuite/libffi.call/cls_8byte.c, testsuite/libffi.call/cls_9byte1.c, testsuite/libffi.call/cls_9byte2.c, testsuite/libffi.call/cls_align_double.c, testsuite/libffi.call/cls_align_float.c, testsuite/libffi.call/cls_align_longdouble.c, testsuite/libffi.call/cls_align_longdouble_split.c, testsuite/libffi.call/cls_align_longdouble_split2.c, testsuite/libffi.call/cls_align_pointer.c, testsuite/libffi.call/cls_align_sint16.c, testsuite/libffi.call/cls_align_sint32.c, testsuite/libffi.call/cls_align_sint64.c, testsuite/libffi.call/cls_align_uint16.c, testsuite/libffi.call/cls_align_uint32.c, testsuite/libffi.call/cls_align_uint64.c, testsuite/libffi.call/cls_dbls_struct.c, testsuite/libffi.call/cls_double.c, testsuite/libffi.call/cls_double_va.c, testsuite/libffi.call/cls_float.c, testsuite/libffi.call/cls_longdouble.c, testsuite/libffi.call/cls_longdouble_va.c, testsuite/libffi.call/cls_multi_schar.c, testsuite/libffi.call/cls_multi_sshort.c, testsuite/libffi.call/cls_multi_sshortchar.c, testsuite/libffi.call/cls_multi_uchar.c, testsuite/libffi.call/cls_multi_ushort.c, testsuite/libffi.call/cls_multi_ushortchar.c, testsuite/libffi.call/cls_pointer.c, testsuite/libffi.call/cls_pointer_stack.c, testsuite/libffi.call/cls_schar.c, testsuite/libffi.call/cls_sint.c, testsuite/libffi.call/cls_sshort.c, testsuite/libffi.call/cls_uchar.c, testsuite/libffi.call/cls_uint.c, testsuite/libffi.call/cls_ulonglong.c, testsuite/libffi.call/cls_ushort.c, testsuite/libffi.call/err_bad_abi.c, testsuite/libffi.call/err_bad_typedef.c, testsuite/libffi.call/float2.c, testsuite/libffi.call/huge_struct.c, testsuite/libffi.call/nested_struct.c, testsuite/libffi.call/nested_struct1.c, testsuite/libffi.call/nested_struct10.c, testsuite/libffi.call/nested_struct2.c, testsuite/libffi.call/nested_struct3.c, testsuite/libffi.call/nested_struct4.c, testsuite/libffi.call/nested_struct5.c, testsuite/libffi.call/nested_struct6.c, testsuite/libffi.call/nested_struct7.c, testsuite/libffi.call/nested_struct8.c, testsuite/libffi.call/nested_struct9.c, testsuite/libffi.call/problem1.c, testsuite/libffi.call/return_ldl.c, testsuite/libffi.call/return_ll1.c, testsuite/libffi.call/stret_large.c, testsuite/libffi.call/stret_large2.c, testsuite/libffi.call/stret_medium.c, testsuite/libffi.call/stret_medium2.c, testsuite/libffi.special/unwindtest.cc: use ffi_closure_alloc instead of checking for MMAP. Use intptr_t instead of long casts. 2009-06-12 Andrew Haley <aph@redhat.com> * Makefile.am: Remove info_TEXINFOS. From-SVN: r148433
2009-06-12 17:57:58 +02:00
must point to storage that is sizeof(ffi_arg) or larger for non-floating point
types. For smaller-sized return value types, the
.Nm ffi_arg
or
.Nm ffi_sarg
integral type must be used to hold
the return value.
.Sh EXAMPLES
.Bd -literal
2009-12-26 06:01:43 +01:00
#include <ffi.h>
#include <stdio.h>
unsigned char
foo(unsigned int, float);
int
main(int argc, const char **argv)
{
ffi_cif cif;
ffi_type *arg_types[2];
void *arg_values[2];
ffi_status status;
// Because the return value from foo() is smaller than sizeof(long), it
// must be passed as ffi_arg or ffi_sarg.
ffi_arg result;
// Specify the data type of each argument. Available types are defined
// in <ffi/ffi.h>.
arg_types[0] = &ffi_type_uint;
arg_types[1] = &ffi_type_float;
// Prepare the ffi_cif structure.
if ((status = ffi_prep_cif(&cif, FFI_DEFAULT_ABI,
2, &ffi_type_uint8, arg_types)) != FFI_OK)
{
// Handle the ffi_status error.
}
// Specify the values of each argument.
unsigned int arg1 = 42;
float arg2 = 5.1;
arg_values[0] = &arg1;
arg_values[1] = &arg2;
// Invoke the function.
ffi_call(&cif, FFI_FN(foo), &result, arg_values);
// The ffi_arg 'result' now contains the unsigned char returned from foo(),
// which can be accessed by a typecast.
printf("result is %hhu", (unsigned char)result);
return 0;
}
// The target function.
unsigned char
foo(unsigned int x, float y)
{
unsigned char result = x - y;
return result;
}
.Ed
.Sh SEE ALSO
.Xr ffi 3 ,
.Xr ffi_prep_cif 3