# illumos-nvpair-sys

Raw Rust FFI bindings to illumos
[libnvpair](https://illumos.org/man/3LIB/libnvpair), generated from the
system header `sys/nvpair.h` (documented by `wrapper.h` in this
directory).

## How bindings are generated

The bindings in `src/lib.rs` are pre-generated by
[bindgen](https://github.com/rust-lang/rust-bindgen) and checked into
source control. Bindgen is **not** run at build time - `build.rs` only
contains a linker directive (`cargo:rustc-link-lib=nvpair`).

To regenerate, run `generate.sh` on an illumos machine with `bindgen`
installed (`cargo install bindgen-cli`):

```
./generate.sh
```

The script runs bindgen with the following flags:

- `--allowlist-function 'nvlist_.*'` and `--allowlist-function 'nvpair_.*'`
  - emit only nvlist/nvpair symbols, not the entire transitive header tree
- `--allowlist-var 'NV_.*'` and `--allowlist-var 'data_type_t_.*'` -
  capture constants like `NV_UNIQUE_NAME` and `data_type_t_DATA_TYPE_STRING`
- `--raw-line '#![allow(...)]'` - prepend an attribute to suppress
  warnings on the `snake_case` and `UPPER_CASE` names that bindgen
  produces for C typedefs and enum-style constants

The nvpair ABI is version 0 and effectively frozen - it is used
throughout illumos (ZFS, FMA, sysevent, etc.) and has not had a breaking
change.
