ffi 1.9.24 → 1.16.3

data/ext/ffi_c/libffi/doc/libffi.texi

@@ -1,7 +1,8 @@
 \input texinfo   @c -*-texinfo-*-
 @c %**start of header
 @setfilename libffi.info
-@settitle libffi
+@include version.texi
+@settitle libffi: the portable foreign function interface library
 @setchapternewpage off
 @c %**end of header
 
@@ -12,32 +13,43 @@
 @syncodeindex pg cp
 @syncodeindex tp cp
 
-@include version.texi
-
 @copying
 
-This manual is for Libffi, a portable foreign-function interface
+This manual is for libffi, a portable foreign function interface
 library.
 
-Copyright @copyright{} 2008, 2010, 2011 Red Hat, Inc.
+Copyright @copyright{} 2008--2019, 2021, 2022 Anthony Green and Red Hat, Inc.
 
-@quotation
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU General Public License as published by the
-Free Software Foundation; either version 2, or (at your option) any
-later version.  A copy of the license is included in the
-section entitled ``GNU General Public License''.
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+``Software''), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED ``AS IS'', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 
-@end quotation
 @end copying
 
 @dircategory Development
 @direntry
-* libffi: (libffi).             Portable foreign-function interface library.
+* libffi: (libffi).             Portable foreign function interface library.
 @end direntry
 
 @titlepage
-@title Libffi
+@title libffi: a foreign function interface library
+@subtitle For Version @value{VERSION} of libffi
+@author Anthony Green
 @page
 @vskip 0pt plus 1filll
 @insertcopying
@@ -53,6 +65,7 @@ section entitled ``GNU General Public License''.
 @menu
 * Introduction::                What is libffi?
 * Using libffi::                How to use libffi.
+* Memory Usage::                Where memory for closures comes from.
 * Missing Features::            Things libffi can't do.
 * Index::                       Index.
 @end menu
@@ -78,10 +91,10 @@ sometimes called the @dfn{ABI} or @dfn{Application Binary Interface}.
 Some programs may not know at the time of compilation what arguments
 are to be passed to a function.  For instance, an interpreter may be
 told at run-time about the number and types of arguments used to call
-a given function.  @samp{Libffi} can be used in such programs to
+a given function.  @code{libffi} can be used in such programs to
 provide a bridge from the interpreter program to compiled code.
 
-The @samp{libffi} library provides a portable, high level programming
+The @code{libffi} library provides a portable, high level programming
 interface to various calling conventions.  This allows a programmer to
 call any function specified by a call interface description at run
 time.
@@ -89,9 +102,9 @@ time.
 @acronym{FFI} stands for Foreign Function Interface.  A foreign
 function interface is the popular name for the interface that allows
 code written in one language to call code written in another language.
-The @samp{libffi} library really only provides the lowest, machine
+The @code{libffi} library really only provides the lowest, machine
 dependent layer of a fully featured foreign function interface.  A
-layer must exist above @samp{libffi} that handles type conversions for
+layer must exist above @code{libffi} that handles type conversions for
 values passed between the two languages.
 @cindex FFI
 @cindex Foreign Function Interface
@@ -114,7 +127,7 @@ values passed between the two languages.
 @node The Basics
 @section The Basics
 
-@samp{Libffi} assumes that you have a pointer to the function you wish
+@code{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.
 
@@ -164,6 +177,11 @@ variadic arguments.  It must be greater than zero.
 @var{ntotalargs} the total number of arguments, including variadic
 and fixed arguments.  @var{argtypes} must have this many elements.
 
+@code{ffi_prep_cif_var} will return @code{FFI_BAD_ARGTYPE} if any of
+the variable argument types are @code{ffi_type_float} (promote to
+@code{ffi_type_double} first), or any integer type small than an int
+(promote to an int-sized type first).
+
 Note that, different cif's must be prepped for calls to the same
 function when different numbers of arguments are passed.
 
@@ -195,22 +213,20 @@ to ensure this.  If @var{cif} declares that the function returns
 @code{void} (using @code{ffi_type_void}), then @var{rvalue} is
 ignored.
 
-In most situations, @samp{libffi} will handle promotion according to
+In most situations, @code{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 @code{struct}) types that are narrower than the
 system register size, the return value will be widened by
-@samp{libffi}.  @samp{libffi} provides a type, @code{ffi_arg}, that
+@code{libffi}.  @code{libffi} provides a type, @code{ffi_arg}, that
 can be used as the return type.  For example, if the CIF was defined
-with a return type of @code{char}, @samp{libffi} will try to store a
+with a return type of @code{char}, @code{libffi} will try to store a
 full @code{ffi_arg} into the return value.
 
 @var{avalues} is a vector of @code{void *} pointers that point to the
 memory locations holding the argument values for a call.  If @var{cif}
 declares that the function has no arguments (i.e., @var{nargs} was 0),
-then @var{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.
+then @var{avalues} is ignored.
 
 Note that while the return value must be register-sized, arguments
 should exactly match their declared type.  For example, if an argument
@@ -237,26 +253,26 @@ int main()
   void *values[1];
   char *s;
   ffi_arg rc;
-  
-  /* Initialize the argument info vectors */    
+
+  /* Initialize the argument info vectors */
   args[0] = &ffi_type_pointer;
   values[0] = &s;
-  
+
   /* Initialize the cif */
-  if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1, 
+  if (ffi_prep_cif(&cif, FFI_DEFAULT_ABI, 1,
 		       &ffi_type_sint, args) == FFI_OK)
     @{
       s = "Hello World!";
       ffi_call(&cif, puts, &rc, values);
       /* rc now holds the result of the call to puts */
-      
-      /* values holds a pointer to the function's arg, so to 
-         call puts() again all we need to do is change the 
+
+      /* values holds a pointer to the function's arg, so to
+         call puts() again all we need to do is change the
          value of s */
       s = "This is cool!";
       ffi_call(&cif, puts, &rc, values);
     @}
-  
+
   return 0;
 @}
 @end example
@@ -394,8 +410,8 @@ when passing to @code{ffi_prep_cif}.
 @node Structures
 @subsection Structures
 
-@samp{libffi} is perfectly happy passing structures back and forth.
-You must first describe the structure to @samp{libffi} by creating a
+@code{libffi} is perfectly happy passing structures back and forth.
+You must first describe the structure to @code{libffi} by creating a
 new @code{ffi_type} object for it.
 
 @tindex ffi_type
@@ -415,7 +431,7 @@ For a structure, this should be set to @code{FFI_TYPE_STRUCT}.
 This is a @samp{NULL}-terminated array of pointers to @code{ffi_type}
 objects.  There is one element per field of the struct.
 
-Note that @samp{libffi} has no special support for bit-fields.  You
+Note that @code{libffi} has no special support for bit-fields.  You
 must manage these manually.
 @end table
 @end deftp
@@ -492,7 +508,7 @@ valid here.
 
 @subsubsection Arrays
 
-@samp{libffi} does not have direct support for arrays or unions.
+@code{libffi} does not have direct support for arrays or unions.
 However, they can be emulated using structures.
 
 To emulate an array, simply create an @code{ffi_type} using
@@ -519,7 +535,7 @@ structure types created like this should only be used to refer to
 members of real @code{FFI_TYPE_STRUCT} objects.
 
 However, a phony array type like this will not cause any errors from
-@samp{libffi} if you use it as an argument or return type.  This may
+@code{libffi} if you use it as an argument or return type.  This may
 be confusing.
 
 @subsubsection Unions
@@ -612,7 +628,7 @@ Here is the corresponding code to describe this struct to
       tm_type.size = tm_type.alignment = 0;
       tm_type.type = FFI_TYPE_STRUCT;
       tm_type.elements = &tm_type_elements;
-    
+
       for (i = 0; i < 9; i++)
           tm_type_elements[i] = &ffi_type_sint;
 
@@ -628,7 +644,7 @@ Here is the corresponding code to describe this struct to
 @node Complex
 @subsection Complex Types
 
-@samp{libffi} supports the complex types defined by the C99
+@code{libffi} supports the complex types defined by the C99
 standard (@code{_Complex float}, @code{_Complex double} and
 @code{_Complex long double} with the built-in type descriptors
 @code{ffi_type_complex_float}, @code{ffi_type_complex_double} and
@@ -636,7 +652,7 @@ standard (@code{_Complex float}, @code{_Complex double} and
 
 Custom complex types like @code{_Complex int} can also be used.
 An @code{ffi_type} object has to be defined to describe the
-complex type to @samp{libffi}.
+complex type to @code{libffi}.
 
 @tindex ffi_type
 @deftp {Data type} ffi_type
@@ -803,7 +819,6 @@ Free memory allocated using @code{ffi_closure_alloc}.  The argument is
 the writable address that was returned.
 @end defun
 
-
 Once you have allocated the memory for a closure, you must construct a
 @code{ffi_cif} describing the function call.  Finally you can prepare
 the closure function:
@@ -875,7 +890,7 @@ writable and executable addresses.
 @node Closure Example
 @section Closure Example
 
-A trivial example that creates a new @code{puts} by binding 
+A trivial example that creates a new @code{puts} by binding
 @code{fputs} with @code{stdout}.
 
 @example
@@ -953,6 +968,55 @@ Currently the only affected platform is PowerPC and the only affected
 type is @code{long double}.
 @end itemize
 
+@node Memory Usage
+@chapter Memory Usage
+
+Note that memory allocated by @code{ffi_closure_alloc} and freed by
+@code{ffi_closure_free} does not come from the same general pool of
+memory that @code{malloc} and @code{free} use.  To accomodate security
+settings, @code{libffi} may aquire memory, for example, by mapping
+temporary files into multiple places in the address space (once to
+write out the closure, a second to execute it).  The search follows
+this list, using the first that works:
+
+@itemize @bullet
+
+@item
+A anonymous mapping (i.e. not file-backed)
+
+@item
+@code{memfd_create()}, if the kernel supports it.
+
+@item
+A file created in the directory referenced by the environment variable
+@code{LIBFFI_TMPDIR}.
+
+@item
+Likewise for the environment variable @code{TMPDIR}.
+
+@item
+A file created in @code{/tmp}.
+
+@item
+A file created in @code{/var/tmp}.
+
+@item
+A file created in @code{/dev/shm}.
+
+@item
+A file created in the user's home directory (@code{$HOME}).
+
+@item
+A file created in any directory listed in @code{/etc/mtab}.
+
+@item
+A file created in any directory listed in @code{/proc/mounts}.
+
+@end itemize
+
+If security settings prohibit using any of these for closures,
+@code{ffi_closure_alloc} will fail.
+
 @node Missing Features
 @chapter Missing Features
 
@@ -974,9 +1038,6 @@ The ``raw'' API is undocumented.
 The Go API is undocumented.
 @end itemize
 
-Note that variadic support is very new and tested on a relatively
-small number of platforms.
-
 @node Index
 @unnumbered Index
 

data/ext/ffi_c/libffi/doc/version.texi

@@ -1,4 +1,4 @@
-@set UPDATED 2 April 2018
-@set UPDATED-MONTH April 2018
-@set EDITION 3.3-rc0
-@set VERSION 3.3-rc0
+@set UPDATED 23 October 2022
+@set UPDATED-MONTH October 2022
+@set EDITION 3.4.4
+@set VERSION 3.4.4

data/ext/ffi_c/libffi/fficonfig.h.in

@@ -3,24 +3,20 @@
 /* Define if building universal (internal helper macro) */
 #undef AC_APPLE_UNIVERSAL_BUILD
 
-/* Define to one of `_getb67', `GETB67', `getb67' for Cray-2 and Cray-YMP
-   systems. This function is required for `alloca.c' support on those systems.
-   */
-#undef CRAY_STACKSEG_END
-
-/* Define to 1 if using `alloca.c'. */
-#undef C_ALLOCA
-
 /* Define to the flags needed for the .section .eh_frame directive. */
 #undef EH_FRAME_FLAGS
 
 /* Define this if you want extra debugging. */
 #undef FFI_DEBUG
 
+/* Define this if you want statically defined trampolines */
+#undef FFI_EXEC_STATIC_TRAMP
+
 /* Cannot use PROT_EXEC on this target, so, we revert to alternative means */
 #undef FFI_EXEC_TRAMPOLINE_TABLE
 
-/* Define this if you want to enable pax emulated trampolines */
+/* Define this if you want to enable pax emulated trampolines (experimental)
+   */
 #undef FFI_MMAP_EXEC_EMUTRAMP_PAX
 
 /* Cannot use malloc on this target, so, we revert to alternative means */
@@ -32,11 +28,7 @@
 /* Define this if you do not want support for aggregate types. */
 #undef FFI_NO_STRUCTS
 
-/* Define to 1 if you have `alloca', as a function or macro. */
-#undef HAVE_ALLOCA
-
-/* Define to 1 if you have <alloca.h> and it should be used (not on Ultrix).
-   */
+/* Define to 1 if you have the <alloca.h> header file. */
 #undef HAVE_ALLOCA_H
 
 /* Define if your assembler supports .cfi_* directives. */
@@ -76,23 +68,11 @@
 /* Define to 1 if you have the `memcpy' function. */
 #undef HAVE_MEMCPY
 
-/* Define to 1 if you have the <memory.h> header file. */
-#undef HAVE_MEMORY_H
-
-/* Define to 1 if you have the `mkostemp' function. */
-#undef HAVE_MKOSTEMP
+/* Define to 1 if you have the `memfd_create' function. */
+#undef HAVE_MEMFD_CREATE
 
-/* Define to 1 if you have the `mmap' function. */
-#undef HAVE_MMAP
-
-/* Define if mmap with MAP_ANON(YMOUS) works. */
-#undef HAVE_MMAP_ANON
-
-/* Define if mmap of /dev/zero works. */
-#undef HAVE_MMAP_DEV_ZERO
-
-/* Define if read-only mmap of a plain file works. */
-#undef HAVE_MMAP_FILE
+/* Define if your compiler supports pointer authentication. */
+#undef HAVE_PTRAUTH
 
 /* Define if .eh_frame sections should be read-only. */
 #undef HAVE_RO_EH_FRAME
@@ -100,6 +80,9 @@
 /* Define to 1 if you have the <stdint.h> header file. */
 #undef HAVE_STDINT_H
 
+/* Define to 1 if you have the <stdio.h> header file. */
+#undef HAVE_STDIO_H
+
 /* Define to 1 if you have the <stdlib.h> header file. */
 #undef HAVE_STDLIB_H
 
@@ -109,8 +92,8 @@
 /* Define to 1 if you have the <string.h> header file. */
 #undef HAVE_STRING_H
 
-/* Define to 1 if you have the <sys/mman.h> header file. */
-#undef HAVE_SYS_MMAN_H
+/* Define to 1 if you have the <sys/memfd.h> header file. */
+#undef HAVE_SYS_MEMFD_H
 
 /* Define to 1 if you have the <sys/stat.h> header file. */
 #undef HAVE_SYS_STAT_H
@@ -157,15 +140,9 @@
 /* The size of `size_t', as computed by sizeof. */
 #undef SIZEOF_SIZE_T
 
-/* If using the C implementation of alloca, define if you know the
-   direction of stack growth for your system; otherwise it will be
-   automatically deduced at runtime.
-	STACK_DIRECTION > 0 => grows toward higher addresses
-	STACK_DIRECTION < 0 => grows toward lower addresses
-	STACK_DIRECTION = 0 => direction of growth unknown */
-#undef STACK_DIRECTION
-
-/* Define to 1 if you have the ANSI C header files. */
+/* Define to 1 if all of the C90 standard headers exist (not just the ones
+   required in a freestanding environment). This macro is provided for
+   backward compatibility; new code need not use it. */
 #undef STDC_HEADERS
 
 /* Define if symbols are underscored. */
@@ -190,13 +167,14 @@
 # endif
 #endif
 
-/* Define to `unsigned int' if <sys/types.h> does not define. */
-#undef size_t
-
 
 #ifdef HAVE_HIDDEN_VISIBILITY_ATTRIBUTE
 #ifdef LIBFFI_ASM
+#ifdef __APPLE__
+#define FFI_HIDDEN(name) .private_extern name
+#else
 #define FFI_HIDDEN(name) .hidden name
+#endif
 #else
 #define FFI_HIDDEN __attribute__ ((visibility ("hidden")))
 #endif