4.1 The Foreign Function Interface

4.1.7 Passing foreign and Lisp data types

You should consider the following information when passing data types to foreign functions from Lisp and vice versa:

• The call discipline indicates the way information passes between a function argument and its associated parameter. The call discipline :value represents call-by-value parameter passing, and:reference represents call-by-reference parameter passing. When the call discipline isnil, the calling standard depends on the Lisp argument type.

• The foreign type:lisp passes a pointer to a Lisp object directly to a foreign function with no further coercion.

• The Lisp typeforeign-pointer is a pointer to an object whose structure is defined bydef-foreign-struct.

• C functions expect strings to end with a null byte. All Common Lisp simple strings are stored with a terminating null byte so that they can be passed to C functions without difficulty. The terminating null byte is not included in the length of the string returned by the Common Lisp function length.

To pass any other type of string to a C function, you must ensure that the string ends with a null byte and declare it to be of typec-string-type.

• The typefortran-string is the same as the following type for byte-addressable machines where the size of a character is one byte:

(subtypep (array-element-type string) 'string-char) 

The length of a string is always passed to FORTRAN functions.

• When passing arrays, the Foreign Function Interface attempts to convert the array to a simple vector of the same type as the array. If the conversion is not possible, an error is signaled.

• The foreign typecoercible-to-foreign-array specifies a Lisp array that can be converted to a foreign array. A coercible Lisp array must be either a simple array, a simple vector, or an array with an offset that is aligned at an offset. You cannot pass, for example, a displaced bit vector to a foreign function because the foreign function is expecting an address, not a pointer.

• All modifiable Lisp data that are passed to a foreign function must be stationary data; that is, they do not move during a garbage collection. Examples of stationary data include data that have been allocated within a call to the macrowith-static-area or symbols that have been freshly created in a package by the Common Lisp functionintern; note that the functionread callsintern. If dynamic data are passed to foreign functions, the results are unpredictable. See the reference page for stationary-object-p for more information.

4.1.7.1 - Passing C data to Lisp functions

4.1.7.2 - Passing FORTRAN data to Lisp functions

4.1.7.3 - Passing Pascal data to Lisp functions

4.1.7.4 - Passing Lisp data to C functions

4.1.7.5 - Passing Lisp data to FORTRAN functions

4.1.7.6 - Passing Lisp data to Pascal functions

Generated with Harlequin WebMaker