Ffikdb function reference¶
.ffi FFI interface
Call function bind bind function to be called callFunction one-off function call
Utility cvar read global variable from the library extension file extension of a shared object os operating system ptrsize size of void* setErrno get or set error number
Argument and result types¶
Throughout the library, characters are used to encode the types of data provided and expected as a result. These are based on the c
column of primitive data types for atoms, with upper case for vectors. The sz
column is useful to work out what type can hold enough data passing to and from C.
The argument types are derived from data passed to the function (in case of callFunction
) or explicitly specified (in case of bind
). The number of character types provided must match the number of arguments expected by the C function.
The return type is specified as a single character and can be " "
(space), which means to discard the result (i.e. void
). If not provided, defaults to int
.
char | C type | FFI type |
---|---|---|
b, c, x | unsigned int8 | ffi_type_uint8 |
h | signed int16 | ffi_type_sint16 |
i, m, d, u, v, t | signed int32 | ffi_type_sint32 |
j, p, n | signed int64 | ffi_type_sint64 |
e | float | ffi_type_float |
f, z | double | ffi_type_double |
g, s | uint8* | ffi_type_pointer |
" " (space) |
void (only as return type) | ffi_type_void |
r | raw pointer | ffi_type_pointer |
l | size of pointer (size_t) | ffi_type_sint32 or ffi_type_sint64 |
k | callback function/closure (only argument type) | ffi_type_pointer |
uppercase letter | pointer to the same type | ffi_type_pointer |
To pass a q function to C code as a callback (see qsort
example below) make the argument type "k"
and represent the function as a mixed list:
(func;argument_types;return_type)
where
func
is a q function (type100h
)argument_types
is the types of the arguments the function expects (string)return_type
is the return type of the function (char atom)
As callbacks can have unbounded life in C code, they are not deleted after the function completes
.ffi.bind
¶
Create a projection with the function resolved to call with arguments
bind[fname;argument_types;return_type]
bind[lfname;argument_types;return_type]
Where
fname
is name of function to look for (symbol atom)lfname
is shared object library and function name (2-item symbol vector)argument_types
is types of arguments (string)return_type
is type of returned value (char atom)
returns a q function, bound to the specifed C function for future calls.
Useful for multiple calls to the C library.
.ffi.callFunction
¶
A simple function call, intended for one-off calls.
callFunction[fname;args]
callFunction[(return_type;fname);args]
callFunction[(return_type;lfname);args]
Where
fname
is name of function to look for (symbol atom)lfname
is shared object library and function name (2-item symbol vector)argument_types
is types of arguments (string)return_type
is type of returned value (char atom)args
: mixed list of arguments to pass to the foreign function; the last item must be the generic null(::)
calls the identified function with the arguments and returns the result.
callFunction
performs function lookup on each call and has significant overhead.
For hot-path functions use .ffi.bind
.ffi.cvar
¶
Read global variable from the library.
.ffi.cvar vname
.ffi.cvar (return_type;lfname)
Where
vname
is a variable name (symbol atom)return_type
is type of returned value (char atom)lfname
is shared object library and function name (2-item symbol vector)
In the second example it is assumed that libsampleparser.so
is exposing a global variable CHUNK_SIZE_THRESHOLD
, i.e. the result of nm
is as below:
$ nm -D l64/libsampleparser.so | grep CHUNK
0000000000054a10 D CHUNK_SIZE_THRESHOLD
Examples:
q).ffi.cvar`timezone
-32400i
q).ffi.cvar ("j"; `libsampleparser.so`CHUNK_SIZE_THRESHOLD)
25000
.ffi.extension
¶
File extension of a shared object for a platform
.ffi.extension[]
Returns symbol atom identifying the file extension for a shared object on the current platform.
q).ffi.extension[]
`so
q)` sv `libRmath, .ffi.extension[]
`libRmath.so
.ffi.os
¶
Identify operating system
.ffi.os[]
Returns char atom identifying the operating system.
q).ffi.os[]
"l"
.ffi.ptrsize
¶
Size of void*
.ffi.ptrsize[]
Returns the size of void*
as an int.
q).ffi.ptrsize[]
8i
.ffi.setErrno
¶
Get or set error number
.ffi.setErrno n
.ffi.setErrno[]
Returns the current value of errno
; if an argument n
is passed it is set as the new value.
q)// No such file or directory
q).ffi.setErrno[]
2i
q)// No such process
q).ffi.setErrno[3i]
2i
q).ffi.setErrno[]
3i