# avril:ffi

`avril:ffi` loads shared libraries and calls their symbols in-process:

```js
import { dlopen } from "avril:ffi";

const lib = dlopen("./libadd.so", {
  add: { parameters: ["i32", "i32"], result: "i32" },
});
console.log(lib.symbols.add(40, 2)); // 42
lib.close();
```

Native code is not sandboxed: it runs with the process's full authority and
a native crash takes the runtime with it. Loading a library therefore
requires the `ffi` capability:

- `avril run --allow-ffi=./libadd.so main.js`, or `--deny-ffi=` to revoke.
  Path grants name one library entry, like `run` grants: aliases and hard
  links need their own entries.
- A bare name (`dlopen("libsqlite3.so")`) is resolved by the system loader
  and requires unrestricted `ffi` authority.
- `pledge({ ffi: false })` (or an allow/deny restriction) narrows it at
  runtime; `-0` starts with none.

## types

`void`, `bool`, `i8`–`i64`, `u8`–`u64`, `isize`, `usize`, `f32`, `f64`,
`pointer`, `buffer` (parameters only), and `function` (parameters and
results). 64-bit integers, `isize`/`usize`, and pointers cross the boundary
as `bigint`. Out-of-range integer arguments throw instead of wrapping.

A definition may set `name` when the symbol differs from its key, and
`nonblocking: true` to run the call on a native thread and return a
`Promise`; `buffer` arguments are copied in for nonblocking calls, and the
bytes the native call changed are written back on completion, while raw
pointers must name memory that outlives the call.

`UnsafePointer` creates and offsets opaque `Pointer`s, `UnsafePointerView`
reads and writes through them (including C strings), and `UnsafeFnPointer`
calls function pointers such as those returned from native code. A
`Pointer` taken from a view does not keep the view alive. Pointer and
function-pointer values obtained from a library dangle once that library is
closed; using them afterwards is undefined behavior. Pointer operations
require holding some `ffi` authority, as `dlopen` does.

Not yet supported: `UnsafeCallback` (JS functions callable from native
code), struct-by-value arguments, and variadic functions.