The define-alien-routine Macro - SBCL 1.0.31 User Manual
Description: SBCL 1.0.31 User Manual

Next: define-alien-routine Example, Previous: The alien-funcall Primitive, Up: Foreign Function Calls

#### 8.7.2 The `define-alien-routine` Macro

— Macro: sb-alien:define-alien-routine name result-type &rest arg-specifiers

> The `define-alien-routine` macro is a convenience for automatically generating Lisp interfaces to simple foreign functions. The primary feature is the parameter style specification, which translates the C pass-by-reference idiom into additional return values.

> name is usually a string external symbol, but may also be a symbol Lisp name or a list of the foreign name and the Lisp name. If only one name is specified, the other is automatically derived as for `extern-alien`. result-type is the alien type of the return value.

> Each element of the arg-specifiers list specifies an argument to the foreign function, and is of the form

>               (aname atype &amp;optional style)

> aname is the symbol name of the argument to the constructed function (for documentation). atype is the alien type of corresponding foreign argument. The semantics of the actual call are the same as for `alien-funcall`. style specifies how this argument should be handled at call and return time, and should be one of the following:

> - `:in` specifies that the argument is passed by value. This is the default. `:in` arguments have no corresponding return value from the Lisp function.
> - `:copy` is similar to `:in`, but the argument is copied to a pre-allocated object and a pointer to this object is passed to the foreign routine.
> - `:out` specifies a pass-by-reference output value. The type of the argument must be a pointer to a fixed-sized object (such as an integer or pointer). `:out` and `:in-out` style cannot be used with pointers to arrays, records or functions. An object of the correct size is allocated on the stack, and its address is passed to the foreign function. When the function returns, the contents of this location are returned as one of the values of the Lisp function (and the location is automatically deallocated).
> - `:in-out` is a combination of `:copy` and `:out`. The argument is copied to a pre-allocated object and a pointer to this object is passed to the foreign routine. On return, the contents of this location is returned as an additional value.

> > Note: Any efficiency-critical foreign interface function should be inline expanded, which can be done by preceding the `define-alien-routine` call with:

> >                    (declaim (inline lisp-name))

> > In addition to avoiding the Lisp call overhead, this allows pointers, word-integers and floats to be passed using non-descriptor representations, avoiding consing.)