Macro

Summary

Defines a Lisp function which acts as an interface to a foreign function.

Package

fli

Signature

define-foreign-function name
 ({arg
}*)

                        &key lambda-list

                             documentation
 result-type
 language

                             no-check
 calling-convention
 module

                             => lisp-name

name
 ::= lisp-name
 | (lisp-name
 foreign-symbol
 [encoding
]) |

         (lisp-name
 foreign-string
 [encoding
])

encoding ::= :source | :object | :lisp | :dbcs

arg
 ::= arg-name
 | (arg-name
 arg-type
) |

        (:constant value
 value-type
)

language ::= :c | :ansi-c calling-convention ::= :stdcall | :cdecl

Arguments

name

Either a symbol naming the defined Lisp function, or a list containing the name of the Lisp function, the corresponding foreign function name and optionally an encoding option.

lisp-name

A symbol naming the defined Lisp function.

foreign-symbol

A symbol naming the foreign function.

foreign-string

A string containing the name of the foreign function.

encoding

An option controlling how the Lisp function name is translated into the function name in the foreign object code. The encoding option can be one of the following:

:source tells LispWorks that the string foreign-string or the symbol foreign-symbol is the name of the function in the foreign source code. This is the default value of encoding .

:object tells LispWorks that the string foreign-string or the symbol foreign-symbol is the literal name of the function in the foreign object code.

:lisp tells LispWorks that the symbol foreign-symbol is a Lisp symbol and must be translated and encoded.

:dbcs adds a suffix onto the function name which will automatically change depending on whether Lisp image is started up in the Windows NT or Windows 95 operating system. The suffix is " A " for Windows 95 and " W " for Windows NT.

arg

Either an argument name, a list containing an argument name and a type, or a list of the form (:constant value value-type ) . Lisp arguments may take any name, but the types must be accurately specified and listed in the same order as in the foreign function, unless otherwise specified using lambda-list .

If only an arg-name is supplied, then define-foreign-function assumes that it is of type :int .

If arg is of the form (:constant value value-type ) then value is always passed through to the foreign code.

lambda-list

The lambda list to be used for the defined Lisp function. If this is not specified, the lambda list is generated from the list of arg s. The lambda-list keyword allows you to define the order in which the Lisp function takes its arguments to be different from the order in which the foreign function takes them, and to use standard lambda list keywords such as &optional . The default value of lambda-list is nil .

documentation

A documentation string for the foreign function.

result-type

The type of the foreign function's return value.

language

The language in which the foreign source code is written. The default is :c .

no-check

If nil , the types of the arguments provided when the Lisp function is called are compared with the expected types and an error is raised if they do not match. Setting no-check to t overrides this check.

If the compilation safety level is set to 0 then no-check is automatically set to t . The default value for no-check is nil .

calling-convention

Specifies the calling convention used.

:stdcall is the calling convention used to call Win32 API functions and matches the C declarator "__stdcall" .

:cdecl is the default calling convention for C/C++ programs and matches the C declarator "__cdecl" .

module

Specifies the module in which the foreign symbol is defined. If it is the name of a module registered using register-module then that module is used to look up the symbol. If the name of the module is a string then that module is automatically registered and used to look up the symbol.

Values

lisp-name

A symbol naming the defined Lisp function.

Description

The macro define-foreign-function defines a Lisp function which acts as an interface to a foreign language function, for example a C function. When the Lisp function is called its arguments are converted to the appropriate foreign representation before being passed to the specified foreign function. Once the foreign function exits, any return values are converted back from the foreign format into a Lisp format.

The number and types of the Lisp function's arguments must be given, and optionally the type of the return value may be specified too. The order in which the Lisp function takes its arguments can be different from the order expected by the foreign function, using the lambda-list argument.

Example

A simple example of the use of define-foreign-function is given in Defining an FLI function. More detailed examples are given in Advanced Uses of the FLI.

See Also

define-foreign-callable

define-foreign-variable

register-module