doc: fix typo
[libffi.git] / doc / libffi.texi
index 125d33d..4f16762 100644 (file)
@@ -174,9 +174,9 @@ Also note that a call to @code{ffi_prep_cif_var} with
 @end defun
 
 Note that the resulting @code{ffi_cif} holds pointers to all the
-@code{ffi_type} objects that were used durin initialization.  You must
-ensure that these type objects have a lifetime at least as long as
-that of the @code{ffi_cif}.
+@code{ffi_type} objects that were used during initialization.  You
+must ensure that these type objects have a lifetime at least as long
+as that of the @code{ffi_cif}.
 
 To call a function using an initialized @code{ffi_cif}, use the
 @code{ffi_call} function:
@@ -269,7 +269,7 @@ int main()
 * Primitive Types::             Built-in types.
 * Structures::                  Structure types.
 * Size and Alignment::          Size and alignment of types.
-* Arrays and Unions::           Arrays and unions.
+* Arrays Unions Enums::         Arrays, unions, and enumerations.
 * Type Example::                Structure type example.
 * Complex::                     Complex types.
 * Complex Type Example::        Complex type example.
@@ -440,7 +440,8 @@ on the chosen ABI.
 
 @item
 The size and alignment of a new structure type will not be set by
-@code{libffi} until it has been passed to @code{ffi_prep_cif}.
+@code{libffi} until it has been passed to @code{ffi_prep_cif} or
+@code{ffi_get_struct_offsets}.
 
 @item
 A structure type cannot be shared across ABIs.  Instead each ABI needs
@@ -448,8 +449,9 @@ its own copy of the structure type.
 @end itemize
 
 So, before examining these fields, it is safest to pass the
-@code{ffi_type} object to @code{ffi_prep_cif} first.  This function
-will do all the needed setup.
+@code{ffi_type} object to @code{ffi_prep_cif} or
+@code{ffi_get_struct_offsets} first.  This function will do all the
+needed setup.
 
 @example
 ffi_type *desired_type;
@@ -463,8 +465,30 @@ if (ffi_prep_cif (&cif, desired_abi, 0, desired_type, NULL) == FFI_OK)
   @}
 @end example
 
-@node Arrays and Unions
-@subsection Arrays and Unions
+@code{libffi} also provides a way to get the offsets of the members of
+a structure.
+
+@findex ffi_get_struct_offsets
+@defun ffi_status ffi_get_struct_offsets (ffi_abi abi, ffi_type *struct_type, size_t *offsets)
+Compute the offset of each element of the given structure type.
+@var{abi} is the ABI to use; this is needed because in some cases the
+layout depends on the ABI.
+
+@var{offsets} is an out parameter.  The caller is responsible for
+providing enough space for all the results to be written -- one
+element per element type in @var{struct_type}.  If @var{offsets} is
+@code{NULL}, then the type will be laid out but not otherwise
+modified.  This can be useful for accessing the type's size or layout,
+as mentioned above.
+
+This function returns @code{FFI_OK} on success; @code{FFI_BAD_ABI} if
+@var{abi} is invalid; or @code{FFI_BAD_TYPEDEF} if @var{struct_type}
+is invalid in some way.  Note that only @code{FFI_STRUCT} types are
+valid here.
+@end defun
+
+@node Arrays Unions Enums
+@subsection Arrays, Unions, and Enumerations
 
 @subsubsection Arrays
 
@@ -541,6 +565,16 @@ for (i = 0; union_elements[i]; ++i)
   @}
 @end example
 
+@subsubsection Enumerations
+
+@code{libffi} does not have any special support for C @code{enum}s.
+Although any given @code{enum} is implemented using a specific
+underlying integral type, exactly which type will be used cannot be
+determined by @code{libffi} -- it may depend on the values in the
+enumeration or on compiler flags such as @option{-fshort-enums}.
+@xref{Structures unions enumerations and bit-fields implementation, , , gcc},
+for more information about how GCC handles enumerations.
+
 @node Type Example
 @subsection Type Example
 
@@ -776,36 +810,47 @@ the closure function:
 
 @findex ffi_prep_closure_loc
 @defun ffi_status ffi_prep_closure_loc (ffi_closure *@var{closure}, ffi_cif *@var{cif}, void (*@var{fun}) (ffi_cif *@var{cif}, void *@var{ret}, void **@var{args}, void *@var{user_data}), void *@var{user_data}, void *@var{codeloc})
-Prepare a closure function.
+Prepare a closure function.  The arguments to
+@code{ffi_prep_closure_loc} are:
 
-@var{closure} is the address of a @code{ffi_closure} object; this is
-the writable address returned by @code{ffi_closure_alloc}.
+@table @var
+@item closure
+The address of a @code{ffi_closure} object; this is the writable
+address returned by @code{ffi_closure_alloc}.
 
-@var{cif} is the @code{ffi_cif} describing the function parameters.
-Note that this object, and the types to which it refers, must be kept
-alive until the closure itself is freed.
+@item cif
+The @code{ffi_cif} describing the function parameters.  Note that this
+object, and the types to which it refers, must be kept alive until the
+closure itself is freed.
 
-@var{user_data} is an arbitrary datum that is passed, uninterpreted,
-to your closure function.
+@item user_data
+An arbitrary datum that is passed, uninterpreted, to your closure
+function.
+
+@item codeloc
+The executable address returned by @code{ffi_closure_alloc}.
 
-@var{codeloc} is the executable address returned by
-@code{ffi_closure_alloc}.
+@item fun
+The function which will be called when the closure is invoked.  It is
+called with the arguments:
 
-@var{fun} is the function which will be called when the closure is
-invoked.  It is called with the arguments:
 @table @var
 @item cif
 The @code{ffi_cif} passed to @code{ffi_prep_closure_loc}.
 
 @item ret
 A pointer to the memory used for the function's return value.
-@var{fun} must fill this, unless the function is declared as returning
-@code{void}.  Note that this points to memory that is exactly the size
-of the type given as the return type when initializing the CIF.  In
-particular, closures do not have the special promotion behavior of
-@code{ffi_call}.
-@c FIXME: is this NULL for void-returning functions?
-@c (experimentally it is not, but it seems like a good idea)
+
+If the function is declared as returning @code{void}, then this value
+is garbage and should not be used.
+
+Otherwise, @var{fun} must fill the object to which this points,
+following the same special promotion behavior as @code{ffi_call}.
+That is, in most cases, @var{ret} points to an object of exactly the
+size of the type specified when @var{cif} was constructed.  However,
+integral types narrower than the system register size are widened.  In
+these cases your program may assume that @var{ret} points to an
+@code{ffi_arg} object.
 
 @item args
 A vector of pointers to memory holding the arguments to the function.
@@ -814,6 +859,7 @@ A vector of pointers to memory holding the arguments to the function.
 The same @var{user_data} that was passed to
 @code{ffi_prep_closure_loc}.
 @end table
+@end table
 
 @code{ffi_prep_closure_loc} will return @code{FFI_OK} if everything
 went ok, and one of the other @code{ffi_status} values on error.