Home | History | Annotate | Download | only in man
      1 .Dd February 15, 2008
      2 .Dt ffi_call 3
      3 .Sh NAME
      4 .Nm ffi_call
      5 .Nd Invoke a foreign function.
      6 .Sh SYNOPSIS
      7 .In ffi.h
      8 .Ft void
      9 .Fo ffi_call
     10 .Fa "ffi_cif *cif"
     11 .Fa "void (*fn)(void)"
     12 .Fa "void *rvalue"
     13 .Fa "void **avalue"
     14 .Fc
     15 .Sh DESCRIPTION
     16 The
     17 .Nm ffi_call
     18 function provides a simple mechanism for invoking a function without
     19 requiring knowledge of the function's interface at compile time.
     20 .Fa fn
     21 is called with the values retrieved from the pointers in the
     22 .Fa avalue
     23 array. The return value from
     24 .Fa fn
     25 is placed in storage pointed to by
     26 .Fa rvalue .
     27 .Fa cif
     28 contains information describing the data types, sizes and alignments of the
     29 arguments to and return value from
     30 .Fa fn ,
     31 and must be initialized with
     32 .Nm ffi_prep_cif
     33 before it is used with
     34 .Nm ffi_call .
     35 .Pp
     36 .Fa rvalue
     37 must point to storage that is sizeof(long) or larger. For smaller
     38 return value sizes, the
     39 .Nm ffi_arg
     40 or
     41 .Nm ffi_sarg
     42 integral type must be used to hold
     43 the return value.
     44 .Sh EXAMPLES
     45 .Bd -literal
     46 #include <ffi/ffi.h>
     47 #include <stdio.h>
     48 
     49 unsigned char
     50 foo(unsigned int, float);
     51 
     52 int
     53 main(int argc, const char **argv)
     54 {
     55     ffi_cif cif;
     56     ffi_type *arg_types[2];
     57     void *arg_values[2];
     58     ffi_status status;
     59 
     60     // Because the return value from foo() is smaller than sizeof(long), it
     61     // must be passed as ffi_arg or ffi_sarg.
     62     ffi_arg result;
     63 
     64     // Specify the data type of each argument. Available types are defined
     65     // in <ffi/ffi.h>.
     66     arg_types[0] = &ffi_type_uint;
     67     arg_types[1] = &ffi_type_float;
     68 
     69     // Prepare the ffi_cif structure.
     70     if ((status = ffi_prep_cif(&cif, FFI_DEFAULT_ABI,
     71         2, &ffi_type_uint8, arg_types)) != FFI_OK)
     72     {
     73         // Handle the ffi_status error.
     74     }
     75 
     76     // Specify the values of each argument.
     77     unsigned int arg1 = 42;
     78     float arg2 = 5.1;
     79 
     80     arg_values[0] = &arg1;
     81     arg_values[1] = &arg2;
     82 
     83     // Invoke the function.
     84     ffi_call(&cif, FFI_FN(foo), &result, arg_values);
     85 
     86     // The ffi_arg 'result' now contains the unsigned char returned from foo(),
     87     // which can be accessed by a typecast.
     88     printf("result is %hhu", (unsigned char)result);
     89 
     90     return 0;
     91 }
     92 
     93 // The target function.
     94 unsigned char
     95 foo(unsigned int x, float y)
     96 {
     97     unsigned char result = x - y;
     98     return result;
     99 }
    100 .Ed
    101 .Sh SEE ALSO
    102 .Xr ffi 3 ,
    103 .Xr ffi_prep_cif 3
    104