C bindings for nix libstore. More...

Files
file	nix_api_store.h
	Main entry for the libstore C bindings.

Typedefs
typedef struct Store	Store
	Reference to a Nix store.

Functions
nix_err	nix_libstore_init (nix_c_context *context)
	Initializes the Nix store library.
nix_err	nix_libstore_init_no_load_config (nix_c_context *context)
	Like nix_libstore_init, but does not load the Nix configuration.
Store *	nix_store_open (nix_c_context context, const char uri, const char ***params)
	Open a nix store.
void	nix_store_free (Store *store)
	Deallocate a nix store and free any resources if not also held by other Store instances.
nix_err	nix_store_get_uri (nix_c_context context, Store store, nix_get_string_callback callback, void *user_data)
	get the URI of a nix store
nix_err	nix_store_get_storedir (nix_c_context context, Store store, nix_get_string_callback callback, void *user_data)
	get the storeDir of a Nix store, typically "/nix/store"
StorePath *	nix_store_parse_path (nix_c_context context, Store store, const char *path)
	Parse a Nix store path that includes the store dir into a StorePath.
bool	nix_store_is_valid_path (nix_c_context context, Store store, const StorePath *path)
	Check if a StorePath is valid (i.e. that corresponding store object and its closure of references exists in the store).
nix_err	nix_store_real_path (nix_c_context context, Store store, StorePath path, nix_get_string_callback callback, void user_data)
	Get the physical location of a store path.
nix_err	nix_store_realise (nix_c_context context, Store store, StorePath path, void userdata, void(callback)(void userdata, const char outname, const StorePath out))
	Realise a Nix store path.
nix_err	nix_store_get_version (nix_c_context context, Store store, nix_get_string_callback callback, void *user_data)
	get the version of a nix store.
nix_derivation *	nix_derivation_from_json (nix_c_context context, Store store, const char *json)
	Create a nix_derivation from a JSON representation of that derivation.
StorePath *	nix_add_derivation (nix_c_context context, Store store, nix_derivation *derivation)
	Add the given nix_derivation to the given store.
nix_err	nix_store_copy_closure (nix_c_context context, Store srcStore, Store dstStore, StorePath path)
	Copy the closure of path from srcStore to dstStore.
nix_err	nix_store_get_fs_closure (nix_c_context context, Store store, const StorePath store_path, bool flip_direction, bool include_outputs, bool include_derivers, void userdata, void(callback)(nix_c_context context, void userdata, const StorePath store_path))
	Gets the closure of a specific store path.
nix_derivation *	nix_store_drv_from_store_path (nix_c_context context, Store store, const StorePath *path)
	Returns the derivation associated with the store path.
StorePath *	nix_store_query_path_from_hash_part (nix_c_context context, Store store, const char *hash)
	Query the full store path given the hash part of a valid store path, or empty if no matching path is found.
nix_err	nix_store_copy_path (nix_c_context context, Store srcStore, Store dstStore, const StorePath path, bool repair, bool checkSigs)
	Copy a path from one store to another.

Detailed Description

C bindings for nix libstore.

libstore is used for talking to a Nix store

Function Documentation

◆ nix_add_derivation()

StorePath * nix_add_derivation	(	nix_c_context *	context,
		Store *	store,
		nix_derivation *	derivation )

Add the given nix_derivation to the given store.

Parameters

[out]	context	Optional, stores error information.
[in]	store	nix store reference. The derivation will be inserted here.
[in]	derivation	nix_derivation to insert into the given store.

◆ nix_derivation_from_json()

nix_derivation * nix_derivation_from_json	(	nix_c_context *	context,
		Store *	store,
		const char *	json )

Create a nix_derivation from a JSON representation of that derivation.

Note: Unlike nix_derivation_to_json, this needs a Store. This is because over time we expect the internal representation of derivations in Nix to differ from accepted derivation formats. The store argument is here to help any logic needed to convert from JSON to the internal representation, in excess of just parsing.

Parameters

[out]	context	Optional, stores error information.
[in]	store	nix store reference.
[in]	json	JSON of the derivation as a string.

Returns: A new derivation, or NULL on error. Free with nix_derivation_free when done using the nix_derivation.

◆ nix_libstore_init()

nix_err nix_libstore_init ( nix_c_context * context )

Initializes the Nix store library.

This function should be called before creating a Store This function can be called multiple times.

Parameters

[out] context Optional, stores error information

Returns: NIX_OK if the initialization was successful, an error code otherwise.

◆ nix_libstore_init_no_load_config()

nix_err nix_libstore_init_no_load_config ( nix_c_context * context )

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_store_copy_closure()

nix_err nix_store_copy_closure	(	nix_c_context *	context,
		Store *	srcStore,
		Store *	dstStore,
		StorePath *	path )

Copy the closure of path from srcStore to dstStore.

Parameters

[out]	context	Optional, stores error information
[in]	srcStore	nix source store reference
[in]	dstStore	nix destination store reference
[in]	path	Path to copy

◆ nix_store_copy_path()

nix_err nix_store_copy_path	(	nix_c_context *	context,
		Store *	srcStore,
		Store *	dstStore,
		const StorePath *	path,
		bool	repair,
		bool	checkSigs )

Copy a path from one store to another.

Parameters

[out]	context	Optional, stores error information
[in]	srcStore	nix source store reference
[in]	dstStore	nix destination store reference
[in]	path	The path to copy
[in]	repair	Whether to repair the path
[in]	checkSigs	Whether to check path signatures are trusted before copying

◆ nix_store_drv_from_store_path()

nix_derivation * nix_store_drv_from_store_path	(	nix_c_context *	context,
		Store *	store,
		const StorePath *	path )

Returns the derivation associated with the store path.

Parameters

[out]	context	Optional, stores error information
[in]	store	The nix store
[in]	path	The nix store path

Returns: A new derivation, or NULL on error. Free with nix_derivation_free when done using the nix_derivation.

◆ nix_store_free()

void nix_store_free ( Store * store )

Deallocate a nix store and free any resources if not also held by other Store instances.

Does not fail.

Parameters

[in] store the store to free

◆ nix_store_get_fs_closure()

nix_err nix_store_get_fs_closure	(	nix_c_context *	context,
		Store *	store,
		const StorePath *	store_path,
		bool	flip_direction,
		bool	include_outputs,
		bool	include_derivers,
		void *	userdata,
		void(*	callback )(nix_c_context context, void userdata, const StorePath *store_path) )

Gets the closure of a specific store path.

Note: The callback borrows each StorePath only for the duration of the call.

Parameters

[out]	context	Optional, stores error information
[in]	store	nix store reference
[in]	store_path	The path to compute from
[in]	flip_direction	If false, compute the forward closure (paths referenced by any store path in the closure). If true, compute the backward closure (paths that reference any store path in the closure).
[in]	include_outputs	If flip_direction is false: for any derivation in the closure, include its outputs. If flip_direction is true: for any output in the closure, include derivations that produce it.
[in]	include_derivers	If flip_direction is false: for any output in the closure, include the derivation that produced it. If flip_direction is true: for any derivation in the closure, include its outputs.
[in]	callback	The function to call for every store path, in no particular order
[in]	userdata	The userdata to pass to the callback

◆ nix_store_get_storedir()

nix_err nix_store_get_storedir	(	nix_c_context *	context,
		Store *	store,
		nix_get_string_callback	callback,
		void *	user_data )

get the storeDir of a Nix store, typically "/nix/store"

Parameters

[out]	context	Optional, stores error information
[in]	store	nix store reference
[in]	callback	Called with the URI.
[in]	user_data	optional, arbitrary data, passed to the callback when it's called.

See also: nix_get_string_callback

Returns: error code, NIX_OK on success.

◆ nix_store_get_uri()

nix_err nix_store_get_uri	(	nix_c_context *	context,
		Store *	store,
		nix_get_string_callback	callback,
		void *	user_data )

get the URI of a nix store

Parameters

[out]	context	Optional, stores error information
[in]	store	nix store reference
[in]	callback	Called with the URI.
[in]	user_data	optional, arbitrary data, passed to the callback when it's called.

See also: nix_get_string_callback

Returns: error code, NIX_OK on success.

◆ nix_store_get_version()

nix_err nix_store_get_version	(	nix_c_context *	context,
		Store *	store,
		nix_get_string_callback	callback,
		void *	user_data )

get the version of a nix store.

If the store doesn't have a version (like the dummy store), returns an empty string.

Parameters

[out]	context	Optional, stores error information
[in]	store	nix store reference
[in]	callback	Called with the version.
[in]	user_data	optional, arbitrary data, passed to the callback when it's called.

See also: nix_get_string_callback

Returns: error code, NIX_OK on success.

◆ nix_store_is_valid_path()

bool nix_store_is_valid_path	(	nix_c_context *	context,
		Store *	store,
		const StorePath *	path )

Check if a StorePath is valid (i.e. that corresponding store object and its closure of references exists in the store).

Parameters

[out]	context	Optional, stores error information
[in]	store	Nix Store reference
[in]	path	Path to check

Returns: true or false, error info in context

◆ nix_store_open()

Store * nix_store_open	(	nix_c_context *	context,
		const char *	uri,
		const char ***	params )

Open a nix store.

Store instances may share state and resources behind the scenes.

Parameters

[out] context Optional, stores error information

[in]

uri

URI of the Nix store, copied.

If NULL, the store from the settings will be used. Note that "auto" holds a strange middle ground, reading part of the general environment, but not all of it. It ignores NIX_REMOTE and the store option. For this reason, NULL is most likely the better choice.

For supported store URLs, see Store URL format in the Nix Reference Manual.

Parameters

[in]

params

optional, null-terminated array of key-value pairs, e.g. {{"endpoint", "https://s3.local"}}.

See Store Types in the Nix Reference Manual.

Returns: a Store pointer, NULL in case of errors

See also: nix_store_free

◆ nix_store_parse_path()

StorePath * nix_store_parse_path	(	nix_c_context *	context,
		Store *	store,
		const char *	path )

Parse a Nix store path that includes the store dir into a StorePath.

Note: Don't forget to free this path using nix_store_path_free()!

Parameters

[out]	context	Optional, stores error information
[in]	store	nix store reference
[in]	path	Path string to parse, copied

Returns: owned store path, NULL on error

◆ nix_store_query_path_from_hash_part()

StorePath * nix_store_query_path_from_hash_part	(	nix_c_context *	context,
		Store *	store,
		const char *	hash )

Query the full store path given the hash part of a valid store path, or empty if no matching path is found.

Parameters

[out]	context	Optional, stores error information
[in]	store	nix store reference
[in]	hash	Hash part of path as a string

Returns: Store path reference, NULL if no matching path is found.

◆ nix_store_real_path()

nix_err nix_store_real_path	(	nix_c_context *	context,
		Store *	store,
		StorePath *	path,
		nix_get_string_callback	callback,
		void *	user_data )

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.

Parameters

[in]	context	Optional, stores error information
[in]	store	nix store reference
[in]	path	the path to get the real path from
[in]	callback	called with the real path
[in]	user_data	arbitrary data, passed to the callback when it's called.

◆ nix_store_realise()

nix_err nix_store_realise	(	nix_c_context *	context,
		Store *	store,
		StorePath *	path,
		void *	userdata,
		void(*	callback )(void userdata, const char outname, const StorePath *out) )

Realise a Nix store path.

Blocking, calls callback once for each realised output.

Note: When working with expressions, consider using e.g. nix_string_realise to get the output. .drvPath may not be accurate or available in the future. See https://github.com/NixOS/nix/issues/6507

Parameters

[out]	context	Optional, stores error information
[in]	store	Nix Store reference
[in]	path	Path to build
[in]	userdata	data to pass to every callback invocation
[in]	callback	called for every realised output

Returns: NIX_OK if the build succeeded, or an error code if the build/scheduling/outputs/copying/etc failed. On error, the callback is never invoked and error information is stored in context.

Files

Typedefs

Functions

Detailed Description

Function Documentation

◆ nix_add_derivation()

◆ nix_derivation_from_json()

◆ nix_libstore_init()

◆ nix_libstore_init_no_load_config()

◆ nix_store_copy_closure()

◆ nix_store_copy_path()

◆ nix_store_drv_from_store_path()

◆ nix_store_free()

◆ nix_store_get_fs_closure()

◆ nix_store_get_storedir()

◆ nix_store_get_uri()

◆ nix_store_get_version()

◆ nix_store_is_valid_path()

◆ nix_store_open()

◆ nix_store_parse_path()

◆ nix_store_query_path_from_hash_part()

◆ nix_store_real_path()

◆ nix_store_realise()