foreign-function-pointer Function

Summary

Returns a FLI pointer with its address set to the address of a foreign symbol.

Package

fli

Signature

foreign-function-pointer symbol-name => pointer

Arguments

symbol-name⇩

A string or a symbol.

Values

pointer

A FLI pointer.

Description

The function foreign-function-pointer returns a FLI pointer with its address set to the address of a foreign symbol, which can be either a symbol defined in a foreign library or a foreign callable.

symbol-name needs to be a name of a foreign symbol specifying a foreign function, either a string naming a symbol defined in a foreign library, or a symbol naming a foreign callable (defined by define-foreign-callable).

foreign-function-pointer returns a FLI pointer with its address set to the address of the symbol. If the symbol is not defined yet an error is signaled.

The pointer that is returned is associated with the symbol and is returned in further calls to foreign-function-pointer with the same argument. The pointer must not be modified by functions like incf-pointer.

When a saved image is restarted all the pointers that have been returned by foreign-function-pointer are updated to reflect the current address of their symbol (which may be different in the new invocation).

Notes

1. The pointer is not updated if the module containing the symbol is disconnected and registered again.
2. Only the pointer itself is updated, but not any copies of it. foreign-function-pointer is very similar to calling make-pointer with symbol-name, with the following differences:
   • The result of foreign-function-pointer is updated on image restart.
   • foreign-function-pointer returns the same pointer for the same symbol-name each time, so modifying the pointer will break it.
   • foreign-function-pointer allocates only in the first call for each symbol. In contrast, make-pointer allocates a pointer in each call.
   • foreign-function-pointer keeps the pointer, so if you want to use it only once, make-pointer is better.
3. foreign-function-pointer is especially useful for creating pointers for passing the address of foreign callables to foreign code in situations where the same address is used repeatedly.

See also

define-foreign-callable
make-pointer
3.1.1 Creating pointers