alien-invoke ( args... return library function parameters varargs? -- return... )
Factor handbook » C library interface » Calling C from Factor

Prev:	FUNCTION-ALIAS:
Next:	alien-indirect ( args... funcptr return parameters abi -- return... )

Vocabulary
alien

Inputs

args...	zero or more objects passed to the C function
return	a C return type
library	a logical library name
function	a C function name
parameters	a sequence of C parameter types
varargs?	false, true, or the number of named parameters

Outputs

return...

the return value of the function, if not void

Word description
Calls a C library function with the given name. Input parameters are taken from the data stack, and the return value is pushed on the data stack after the function returns. A return type of void indicates that no value is to be expected.

Notes
For variadic calls, supply the number of named parameters as an integer. Parameters following that boundary receive C default argument promotions. Types are normalized before coercion, so supply the intended promoted values; explicitly round first if an intermediate C float cast is required. This count is required on macOS ARM64, where unnamed parameters use the stack. The legacy boolean true is rejected on macOS ARM64 because it does not specify this boundary; other architectures retain its previous behavior. C type names are documented in C type specifiers.

Errors
Throws an callsite-not-compiled if the word calling alien-invoke was not compiled with the optimizing compiler.

See also
alien-indirect, alien-indirect-varargs, alien-assembly, alien-callback, alien-callback-varargs

Definition

IN: alien

: alien-invoke
    ( args... return library function parameters varargs? -- return... )
    \ alien-invoke callsite-not-compiled ;