Skip to main content

Crate nix_bindings_sys

Crate nix_bindings_sys 

Source
Expand description

§nix-bindings-sys

Raw, unsafe FFI bindings to the Nix C API.

§Safety

These bindings are generated automatically and map directly to the C API. They are unsafe to use directly. Prefer using the high-level safe API in the parent crate unless you know what you’re doing.

Structs§

BindingsBuilder
EvalState
ExternalValue
ListBuilder
NixCExternalValueDesc
Definition for a class of external values Create and implement one of these, then pass it to nix_create_external_value Make sure to keep it alive while the external value lives. Optional functions can be set to NULL
PrimOp
Store
StorePath
__fsid_t
max_align_t
nix_c_context
nix_derivation
nix_eval_state_builder
nix_fetchers_settings
nix_flake_lock_flags
nix_flake_reference
nix_flake_reference_parse_flags
nix_flake_settings
nix_locked_flake
nix_printer
nix_realised_string
nix_store_path_hash_part
A store path hash Once decoded from “nix32” encoding, a store path hash is 20 raw bytes.
nix_string_context
nix_string_return
nix_value

Constants§

INT8_MAX
INT8_MIN
INT16_MAX
INT16_MIN
INT32_MAX
INT32_MIN
INTPTR_MAX
INTPTR_MIN
INT_FAST8_MAX
INT_FAST8_MIN
INT_FAST16_MAX
INT_FAST16_MIN
INT_FAST32_MAX
INT_FAST32_MIN
INT_LEAST8_MAX
INT_LEAST8_MIN
INT_LEAST16_MAX
INT_LEAST16_MIN
INT_LEAST32_MAX
INT_LEAST32_MIN
PTRDIFF_MAX
PTRDIFF_MIN
SIG_ATOMIC_MAX
SIG_ATOMIC_MIN
SIZE_MAX
UINT8_MAX
UINT16_MAX
UINT32_MAX
UINTPTR_MAX
UINT_FAST8_MAX
UINT_FAST16_MAX
UINT_FAST32_MAX
UINT_LEAST8_MAX
UINT_LEAST16_MAX
UINT_LEAST32_MAX
ValueType_NIX_TYPE_ATTRS
Attribute set (key-value mapping)
ValueType_NIX_TYPE_BOOL
Boolean true or false value
ValueType_NIX_TYPE_EXTERNAL
External value from C++ plugins or C API
ValueType_NIX_TYPE_FAILED
External value from C++ plugins or C API
ValueType_NIX_TYPE_FLOAT
IEEE 754 double precision floating point number
ValueType_NIX_TYPE_FUNCTION
Function (lambda or builtin)
ValueType_NIX_TYPE_INT
A 64 bit signed integer.
ValueType_NIX_TYPE_LIST
Ordered list of values
ValueType_NIX_TYPE_NULL
Null value
ValueType_NIX_TYPE_PATH
Filesystem path
ValueType_NIX_TYPE_STRING
String value with context String content may contain arbitrary bytes, not necessarily UTF-8.
ValueType_NIX_TYPE_THUNK
Unevaluated expression Thunks often contain an expression and closure, but may contain other representations too. Their state is mutable, unlike that of the other types.
WINT_MAX
WINT_MIN
_ATFILE_SOURCE
_BITS_STDINT_INTN_H
_BITS_STDINT_LEAST_H
_BITS_STDINT_UINTN_H
_BITS_TIME64_H
_BITS_TYPESIZES_H
_BITS_TYPES_H
_BITS_WCHAR_H
_DEFAULT_SOURCE
_FEATURES_H
_POSIX_C_SOURCE
_POSIX_SOURCE
_STDC_PREDEF_H
_STDINT_H
_SYS_CDEFS_H
__FD_SETSIZE
__GLIBC_MINOR__
__GLIBC_USE_C23_STRTOL
__GLIBC_USE_DEPRECATED_GETS
__GLIBC_USE_DEPRECATED_SCANF
__GLIBC_USE_IEC_60559_BFP_EXT
__GLIBC_USE_IEC_60559_BFP_EXT_C23
__GLIBC_USE_IEC_60559_EXT
__GLIBC_USE_IEC_60559_FUNCS_EXT
__GLIBC_USE_IEC_60559_FUNCS_EXT_C23
__GLIBC_USE_IEC_60559_TYPES_EXT
__GLIBC_USE_ISOC2Y
__GLIBC_USE_ISOC23
__GLIBC_USE_LIB_EXT2
__GLIBC__
__GNU_LIBRARY__
__HAVE_GENERIC_SELECTION
__INO_T_MATCHES_INO64_T
__KERNEL_OLD_TIMEVAL_MATCHES_TIMEVAL64
__LDOUBLE_REDIRECTS_TO_FLOAT128_ABI
__OFF_T_MATCHES_OFF64_T
__RLIM_T_MATCHES_RLIM64_T
__STATFS_MATCHES_STATFS64
__STDC_IEC_559_COMPLEX__
__STDC_IEC_559__
__STDC_IEC_60559_BFP__
__STDC_IEC_60559_COMPLEX__
__STDC_ISO_10646__
__SYSCALL_WORDSIZE
__TIMESIZE
__USE_ATFILE
__USE_FORTIFY_LEVEL
__USE_ISOC11
__USE_ISOC95
__USE_ISOC99
__USE_MISC
__USE_POSIX
__USE_POSIX2
__USE_POSIX199309
__USE_POSIX199506
__USE_POSIX_IMPLICITLY
__USE_TIME_BITS64
__USE_XOPEN2K
__USE_XOPEN2K8
__WORDSIZE
__WORDSIZE_TIME64_COMPAT32
__bool_true_false_are_defined
__glibc_c99_flexarr_available
false_
nix_err_NIX_ERR_KEY
A key/index access error occurred in C API functions. This error code is returned when accessing a key, index, or identifier that does not exist in C API functions. Common scenarios include:
nix_err_NIX_ERR_NIX_ERROR
A generic Nix error occurred. This error code is returned when a generic Nix error occurred during the function execution.
nix_err_NIX_ERR_OVERFLOW
An overflow error occurred. This error code is returned when an overflow error occurred during the function execution.
nix_err_NIX_ERR_RECOVERABLE
A recoverable error occurred. This is used primarily by C API consumers to communicate that a failed primop call should be retried on the next evaluation attempt.
nix_err_NIX_ERR_UNKNOWN
An unknown error occurred. This error code is returned when an unknown error occurred during the function execution.
nix_err_NIX_OK
No error occurred. This error code is returned when no error has occurred during the function execution.
nix_verbosity_NIX_LVL_CHATTY
nix_verbosity_NIX_LVL_DEBUG
nix_verbosity_NIX_LVL_ERROR
nix_verbosity_NIX_LVL_INFO
nix_verbosity_NIX_LVL_NOTICE
nix_verbosity_NIX_LVL_TALKATIVE
nix_verbosity_NIX_LVL_VOMIT
nix_verbosity_NIX_LVL_WARN
true_

Functions§

nix_add_derivation
Add the given nix_derivation to the given store
nix_alloc_primop
Allocate a PrimOp @ingroup primops Call nix_gc_decref() when you’re done with the returned PrimOp.
nix_alloc_value
Allocate a Nix value @ingroup value_create Call nix_value_decref() when you’re done with the pointer
nix_bindings_builder_free
Free a bindings builder Does not fail.
nix_bindings_builder_insert
Insert bindings into a builder
nix_c_context_create
Allocate a new nix_c_context. @throws std::bad_alloc
nix_c_context_free
Free a nix_c_context. Does not fail.
nix_clear_err
Clear the error message from a nix context. This is performed implicitly by all functions that accept a context, so this won’t be necessary in most cases. However, if you want to clear the error message without calling another function, you can use this. Example use case: a higher order function that helps with error handling, to make it more robust in the following scenario:
nix_copy_value
Copy from another value @ingroup value_create
nix_create_external_value
Create an external value, that can be given to nix_init_external Call nix_gc_decref() when you’re done with the pointer.
nix_derivation_clone
Copy a nix_derivation
nix_derivation_free
Deallocate a nix_derivation Does not fail.
nix_derivation_from_json
Create a nix_derivation from a JSON representation of that derivation.
nix_derivation_to_json
Gets the derivation as a JSON string
nix_err_code
Retrieves the most recent error code from a nix_c_context Equivalent to reading the first field of the context. Does not fail
nix_err_info_msg
Retrieves the error message from errorInfo in a context. Used to inspect nix Error messages. @pre This function should only be called after a previous nix function has returned a NIX_ERR_NIX_ERROR
nix_err_msg
@addtogroup errors Retrieves the most recent error message from a context. @pre This function should only be called after a previous nix function has returned an error.
nix_err_name
Retrieves the error name from a context. Used to inspect nix Error messages. @pre This function should only be called after a previous nix function has returned a NIX_ERR_NIX_ERROR
nix_eval_state_allow_path
Register a store path in the evaluator’s access allowlist. In pure evaluation mode (–pure-eval) the Nix evaluator wraps the filesystem in an AllowListSourceAccessor that rejects any path not explicitly permitted. Nix’s own fetch builtins call allowPath after adding a path to the store so that the resulting path value can be used without triggering the access restriction. Call this before nix_init_path_string (or PrimOpRet::set_path) when your primop has added a path to the store and needs to return it as a Nix path value that is usable in pure evaluation mode.
nix_eval_state_build
Create a new Nix language evaluator state @ingroup libexpr_init The builder becomes unusable after this call. Remember to call nix_eval_state_builder_free() after building the state.
nix_eval_state_builder_free
Free a nix_eval_state_builder @ingroup libexpr_init Does not fail.
nix_eval_state_builder_load
Read settings from the ambient environment @ingroup libexpr_init Settings are sourced from environment variables and configuration files, as documented in the Nix manual.
nix_eval_state_builder_new
Create a new nix_eval_state_builder @ingroup libexpr_init The settings are initialized to their default value. Values can be sourced elsewhere with nix_eval_state_builder_load.
nix_eval_state_builder_set_lookup_path
Set the lookup path for <...> expressions @ingroup libexpr_init
nix_expr_eval_from_string
Parses and evaluates a Nix expression from a string. @ingroup value_create
nix_external_add_string_context
Add string context to the nix_string_context object
nix_external_print
Print to the nix_printer
nix_fetchers_settings_free
nix_fetchers_settings_new
nix_flake_lock
Lock a flake, if not already locked.
nix_flake_lock_flags_add_input_override
Add input overrides to the lock flags
nix_flake_lock_flags_free
Deallocate and release the resources associated with a nix_flake_lock_flags. Does not fail.
nix_flake_lock_flags_new
A new nix_flake_lock_flags with defaults
nix_flake_lock_flags_set_mode_check
Put the lock flags in a mode that checks whether the lock is up to date.
nix_flake_lock_flags_set_mode_virtual
Put the lock flags in a mode that updates the lock file in memory, if needed.
nix_flake_lock_flags_set_mode_write_as_needed
Put the lock flags in a mode that updates the lock file on disk, if needed.
nix_flake_reference_and_fragment_from_string
Parse a URL-like string into a nix_flake_reference.
nix_flake_reference_free
Deallocate and release the resources associated with a nix_flake_reference. Does not fail.
nix_flake_reference_parse_flags_free
Deallocate and release the resources associated with a nix_flake_reference_parse_flags. Does not fail.
nix_flake_reference_parse_flags_new
A new nix_flake_reference_parse_flags with defaults
nix_flake_reference_parse_flags_set_base_directory
Provide a base directory for parsing relative flake references
nix_flake_settings_add_to_eval_state_builder
Initialize a nix_flake_settings to contain builtins.getFlake and potentially more. @warning This does not put the eval state in pure mode!
nix_flake_settings_free
Release the resources associated with a nix_flake_settings.
nix_flake_settings_new
Create a nix_flake_settings initialized with default values.
nix_gc_decref
Decrement the garbage collector reference counter for the given object
nix_gc_incref
Increment the garbage collector reference counter for the given object. The Nix language evaluator C API keeps track of alive objects by reference counting. When you’re done with a refcounted pointer, call nix_gc_decref().
nix_gc_now
Trigger the garbage collector manually You should not need to do this, but it can be useful for debugging.
nix_gc_register_finalizer
Register a callback that gets called when the object is garbage collected.
nix_get_attr_byidx
Get an attribute by index @ingroup value_extract Also gives you the name. Attributes are returned in an unspecified order which is NOT suitable for reproducible operations. In Nix’s domain, reproducibility is paramount. The caller is responsible for sorting the attributes or storing them in an ordered map to ensure deterministic behavior in your application.
nix_get_attr_byidx_lazy
Get an attribute by index, without forcing evaluation of the attribute’s value @ingroup value_extract Also gives you the name. Returns the attribute value without forcing its evaluation, allowing access to lazy values. The attribute set value itself must already have been evaluated. Attributes are returned in an unspecified order which is NOT suitable for reproducible operations. In Nix’s domain, reproducibility is paramount. The caller is responsible for sorting the attributes or storing them in an ordered map to ensure deterministic behavior in your application.
nix_get_attr_byname
Get an attr by name @ingroup value_extract Call nix_value_decref() when you’re done with the pointer
nix_get_attr_byname_lazy
Get an attribute value by attribute name, without forcing evaluation of the attribute’s value @ingroup value_extract Returns the attribute value without forcing its evaluation, allowing access to lazy values. The attribute set value itself must already be evaluated. Call nix_value_decref() when you’re done with the pointer
nix_get_attr_name_byidx
Get an attribute name by index @ingroup value_extract Returns the attribute name without forcing evaluation of the attribute’s value. Attributes are returned in an unspecified order which is NOT suitable for reproducible operations. In Nix’s domain, reproducibility is paramount. The caller is responsible for sorting the attributes or storing them in an ordered map to ensure deterministic behavior in your application.
nix_get_attrs_size
Get the element count of an attrset @ingroup value_extract
nix_get_bool
Get boolean value @ingroup value_extract
nix_get_external
Get external reference @ingroup value_extract
nix_get_external_value_content
Extract the pointer from a Nix C API external value.
nix_get_float
Get float value in 64 bits @ingroup value_extract
nix_get_int
Get int value @ingroup value_extract
nix_get_list_byidx
Get the ix’th element of a list @ingroup value_extract Call nix_value_decref() when you’re done with the pointer
nix_get_list_byidx_lazy
Get the ix’th element of a list without forcing evaluation of the element @ingroup value_extract Returns the list element without forcing its evaluation, allowing access to lazy values. The list value itself must already be evaluated. Call nix_value_decref() when you’re done with the pointer
nix_get_list_size
Get the length of a list @ingroup value_extract
nix_get_path_string
Get path as string @ingroup value_extract
nix_get_string
Get the raw string @ingroup value_extract This may contain placeholders.
nix_get_type
Get value type @ingroup value_extract
nix_get_typename
Get type name of value as defined in the evaluator @ingroup value_extract
nix_has_attr_byname
Check if an attribute name exists on a value @ingroup value_extract
nix_init_apply
Set the value to a thunk that will perform a function application when needed. @ingroup value_create Thunks may be put into attribute sets and lists to perform some computation lazily; on demand. However, note that in some places, a thunk must not be returned, such as in the return value of a PrimOp. In such cases, you may use nix_value_call() instead (but note the different argument order).
nix_init_bool
@name Initializers Values are typically “returned” by initializing already allocated memory that serves as the return value. For this reason, the construction of values is not tied their allocation. Nix is a language with immutable values. Respect this property by only initializing Values once; and only initialize Values that are meant to be initialized by you. Failing to adhere to these rules may lead to undefined behavior. @ingroup value_create
nix_init_external
Set an external value @ingroup value_create
nix_init_float
Set a float @ingroup value_create
nix_init_int
Set an int @ingroup value_create
nix_init_null
Set null @ingroup value_create
nix_init_path_string
Set a path @ingroup value_create
nix_init_plugins
Loads the plugins specified in Nix’s plugin-files setting. Call this once, after calling your desired init functions and setting relevant settings.
nix_init_primop
Set primop @ingroup value_create
nix_init_string
Set a string @ingroup value_create
nix_libexpr_init
Initialize the Nix language evaluator. @ingroup libexpr_init This function must be called at least once, at some point before constructing a EvalState for the first time. This function can be called multiple times, and is idempotent.
nix_libstore_init
Initializes the Nix store library This function should be called before creating a Store This function can be called multiple times.
nix_libstore_init_no_load_config
Like nix_libstore_init, but does not load the Nix configuration. This is useful when external configuration is not desired, such as when running unit tests.
nix_libutil_init
Initializes nix_libutil and its dependencies. This function can be called multiple times, but should be called at least once prior to any other nix function.
nix_list_builder_free
Free a list builder Does not fail.
nix_list_builder_insert
Insert bindings into a builder
nix_locked_flake_free
Deallocate and release the resources associated with a nix_locked_flake. Does not fail.
nix_locked_flake_get_output_attrs
Get the output attributes of a flake.
nix_make_attrs
Create an attribute set from a bindings builder @ingroup value_create After this call, the bindings builder becomes invalid and cannot be used again. The only necessary next step is to free it with nix_bindings_builder_free().
nix_make_bindings_builder
Create a bindings builder
nix_make_list
Create a list from a list builder @ingroup value_create After this call, the list builder becomes invalid and cannot be used again. The only necessary next step is to free it with nix_list_builder_free().
nix_make_list_builder
Create a list builder @ingroup value_create
nix_realised_string_free
Free a realised string
nix_realised_string_get_buffer_size
Length of the string
nix_realised_string_get_buffer_start
Start of the string
nix_realised_string_get_store_path
Get a store path. The store paths are stored in an arbitrary order.
nix_realised_string_get_store_path_count
Number of realised store paths
nix_register_primop
add a primop to the builtins attribute set @ingroup primops Only applies to States created after this call. Moves your PrimOp content into the global evaluator registry, meaning your input PrimOp pointer becomes invalid. The PrimOp must not be used with nix_init_primop() before or after this call, as this would cause undefined behavior. You must call nix_gc_decref() on the original PrimOp pointer after this call to release your reference.
nix_set_err_msg
Set an error message on a nix context. This should be used when you want to throw an error from a PrimOp callback. All other use is internal to the API.
nix_set_log_format
Sets the log format
nix_set_string_return
Sets the contents of a nix_string_return Copies the passed string.
nix_set_verbosity
Sets the verbosity level
nix_setting_get
@defgroup settings Nix configuration settings Retrieves a setting from the nix global configuration. This function requires nix_libutil_init() to be called at least once prior to its use.
nix_setting_set
Sets a setting in the nix global configuration. Use “extra-” to append to the setting’s value. Settings only apply for new State%s. Call nix_plugins_init() when you are done with the settings to load any plugins.
nix_state_create
Create a new Nix language evaluator state @ingroup libexpr_init For more control, use nix_eval_state_builder
nix_state_free
Frees a Nix state. @ingroup libexpr_init Does not fail.
nix_store_add_bytes_to_store
Add raw bytes to the store as a flat, content-addressed file. Equivalent to Nix’s builtins.toFile, but accepts arbitrary bytes (including embedded NULs). The content is ingested with the “Text” content-addressing method (flat serialisation, SHA-256). The resulting store path has no references.
nix_store_copy_closure
Copy the closure of path from srcStore to dstStore.
nix_store_copy_path
Copy a path from one store to another.
nix_store_create_from_parts
Create a StorePath from its constituent parts (hash and name) This function constructs a store path from a hash and name, without needing a Store reference or the store directory prefix.
nix_store_drv_from_store_path
Returns the derivation associated with the store path
nix_store_free
Deallocate a nix store and free any resources if not also held by other Store instances. Does not fail.
nix_store_get_fs_closure
Gets the closure of a specific store path
nix_store_get_storedir
get the storeDir of a Nix store, typically "/nix/store"
nix_store_get_uri
get the URI of a nix store
nix_store_get_version
get the version of a nix store. If the store doesn’t have a version (like the dummy store), returns an empty string.
nix_store_is_valid_path
Check if a StorePath is valid (i.e. that corresponding store object and its closure of references exists in the store)
nix_store_open
Open a nix store. Store instances may share state and resources behind the scenes.
nix_store_parse_path
Parse a Nix store path that includes the store dir into a StorePath
nix_store_path_clone
Copy a StorePath
nix_store_path_free
Deallocate a StorePath Does not fail.
nix_store_path_hash
Get the path hash (e.g. “” in /nix/store/-) The hash is returned as raw bytes, decoded from “nix32” encoding.
nix_store_path_name
Get the path name (e.g. “” in /nix/store/-)
nix_store_path_to_string
Render a StorePath as its canonical /nix/store/… string. Calls store->printStorePath(path) and surfaces the result via the standard get-string callback protocol. Unlike nix_store_path_name, which only returns the name component, this returns the full path including the store directory and hash.
nix_store_query_path_from_hash_part
Query the full store path given the hash part of a valid store path, or empty if no matching path is found.
nix_store_real_path
Get the physical location of a store path A store may reside at a different location than its storeDir suggests. This situation is called a relocated store. Relocated stores are used during NixOS installation, as well as in restricted computing environments that don’t offer a writable /nix/store. Not all types of stores support this operation.
nix_store_realise
Realise a Nix store path Blocking, calls callback once for each realised output.
nix_string_realise
Realise a string context. This will
nix_value_call
Calls a Nix function with an argument. @ingroup value_create
nix_value_call_multi
Calls a Nix function with multiple arguments. @ingroup value_create Technically these are functions that return functions. It is common for Nix functions to be curried, so this function is useful for calling them.
nix_value_decref
Decrement the garbage collector reference counter for the given object @ingroup value When the counter reaches zero, the nix_value object becomes invalid. The data referenced by nix_value may not be deallocated until the memory garbage collector has run, but deallocation is not guaranteed.
nix_value_force
Forces the evaluation of a Nix value. @ingroup value_create The Nix interpreter is lazy, and not-yet-evaluated values can be of type NIX_TYPE_THUNK instead of their actual value. This function mutates such a nix_value, so that, if successful, it has its final type.
nix_value_force_deep
Forces the deep evaluation of a Nix value. Recursively calls nix_value_force
nix_value_incref
Increment the garbage collector reference counter for the given nix_value. @ingroup value The Nix language evaluator C API keeps track of alive objects by reference counting. When you’re done with a refcounted pointer, call nix_value_decref().
nix_version_get
Retrieves the nix library version. Does not fail.

Type Aliases§

PrimOpFun
Function pointer for primops @ingroup primops When you want to return an error, call nix_set_err_msg(context, NIX_ERR_UNKNOWN, “your error message here”).
Value
Deprecated Use nix_value instead
ValueType
Represents the state of a Nix value Thunk values (NIX_TYPE_THUNK) change to their final, unchanging type when forced.
__blkcnt64_t
__blkcnt_t
__blksize_t
__caddr_t
__clock_t
__clockid_t
__daddr_t
__dev_t
__fsblkcnt64_t
__fsblkcnt_t
__fsfilcnt64_t
__fsfilcnt_t
__fsword_t
__gid_t
__id_t
__ino64_t
__ino_t
__int8_t
__int16_t
__int32_t
__int64_t
__int_least8_t
__int_least16_t
__int_least32_t
__int_least64_t
__intmax_t
__intptr_t
__key_t
__loff_t
__mode_t
__nlink_t
__off64_t
__off_t
__pid_t
__quad_t
__rlim64_t
__rlim_t
__sig_atomic_t
__socklen_t
__ssize_t
__suseconds64_t
__suseconds_t
__syscall_slong_t
__syscall_ulong_t
__time_t
__timer_t
__u_char
__u_int
__u_long
__u_quad_t
__u_short
__uid_t
__uint8_t
__uint16_t
__uint32_t
__uint64_t
__uint_least8_t
__uint_least16_t
__uint_least32_t
__uint_least64_t
__uintmax_t
__useconds_t
int_fast8_t
int_fast16_t
int_fast32_t
int_fast64_t
int_least8_t
int_least16_t
int_least32_t
int_least64_t
intmax_t
nix_err
Type for error codes in the Nix system This type can have one of several predefined constants:
nix_get_string_callback
Called to get the value of a string owned by Nix. The start data is borrowed and the function must not assume that the buffer persists after it returns.
nix_verbosity
Verbosity level
uint_fast8_t
uint_fast16_t
uint_fast32_t
uint_fast64_t
uint_least8_t
uint_least16_t
uint_least32_t
uint_least64_t
uintmax_t
wchar_t