FFI Module

(ffi/align type)

Get the align of an ffi type in bytes.

(ffi/call pointer signature & args)

Call a raw pointer as a function pointer. The function signature specifies how Janet values in args are converted to native machine types.

(ffi/calling-conventions)

Get an array of all supported calling conventions on the current architecture. Some architectures may have some FFI functionality (ffi/malloc, ffi/free, ffi/read, ffi/write, etc.) but not support any calling conventions. This function can be used to get all supported calling conventions that can be used on this architecture. All architectures support the :none calling convention which is a placeholder that cannot be used at runtime.

(ffi/close native)

Free a native object. Dereferencing pointers to symbols in the object will have undefined behavior after freeing.

(ffi/context &opt native-path &named map-symbols lazy)

Set the path of the dynamic library to implicitly bind, as well as other global state for ease of creating native bindings.

(ffi/defbind name ret-type & body)

Generate bindings for native functions in a convenient manner.

(ffi/defbind-alias name alias ret-type & body)

Generate bindings for native functions in a convenient manner. Similar to defbind but allows for the janet function name to be different than the FFI function.

(ffi/free pointer)

Free memory allocated with ffi/malloc. Returns nil.

(ffi/jitfn bytes)

Create an abstract type that can be used as the pointer argument to ffi/call. The content of bytes is architecture specific machine code that will be copied into executable memory.

(ffi/lookup native symbol-name)

Lookup a symbol from a native object. All symbol lookups will return a raw pointer if the symbol is found, else nil.

(ffi/malloc size)

Allocates memory directly using the janet memory allocator. Memory allocated in this way must be freed manually! Returns a raw pointer, or nil if size = 0.

(ffi/native &opt path)

Load a shared object or dll from the given path, and do not extract or run any code from it. This is different than native, which will run initialization code to get a module table. If path is nil, opens the current running binary. Returns a core/native.

(ffi/pointer-buffer pointer capacity &opt count offset)

Create a buffer from a pointer. The underlying memory of the buffer will not be reallocated or freed by the garbage collector, allowing unmanaged, mutable memory to be manipulated with buffer functions. Attempts to resize or extend the buffer beyond its initial capacity will raise an error. As with many FFI functions, this is memory unsafe and can potentially allow out of bounds memory access. Returns a new buffer.

(ffi/pointer-cfunction pointer &opt name source-file source-line)

Create a C Function from a raw pointer. Optionally give the cfunction a name and source location for stack traces and debugging.

(ffi/read ffi-type bytes &opt offset)

Parse a native struct out of a buffer and convert it to normal Janet data structures. This function is the inverse of ffi/write. bytes can also be a raw pointer, although this is unsafe.

(ffi/signature calling-convention ret-type & arg-types)

Create a function signature object that can be used to make calls with raw function pointers.

(ffi/size type)

Get the size of an ffi type in bytes.

(ffi/struct & types)

Create a struct type definition that can be used to pass structs into native functions.

(ffi/trampoline cc)

Get a native function pointer that can be used as a callback and passed to C libraries. This callback trampoline has the signature void trampoline(void \*ctx, void \*userdata) in the given calling convention. This is the only function signature supported. It is up to the programmer to ensure that the userdata argument contains a janet function the will be called with one argument, ctx which is an opaque pointer. This pointer can be further inspected with ffi/read.

(ffi/write ffi-type data &opt buffer index)

Append a native type to a buffer such as it would appear in memory. This can be used to pass pointers to structs in the ffi, or send C/C++/native structs over the network or to files. Returns a modified buffer or a new buffer if one is not supplied.