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.
typedef struct StorePath	StorePath
	Nix store path.

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 into a StorePath.
void	nix_store_path_name (const StorePath store_path, nix_get_string_callback callback, void user_data)
	Get the path name (e.g. "name" in /nix/store/...-name)
StorePath *	nix_store_path_clone (const StorePath *p)
	Copy a StorePath.
void	nix_store_path_free (StorePath *p)
	Deallocate a StorePath.
bool	nix_store_is_valid_path (nix_c_context context, Store store, 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 char 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_err	nix_store_copy_closure (nix_c_context context, Store srcStore, Store dstStore, StorePath path)
	Copy the closure of path from srcStore to dstStore.

Detailed Description

C bindings for nix libstore.

libstore is used for talking to a Nix store

Function Documentation

◆ 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_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_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,
		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 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_path_clone()

StorePath * nix_store_path_clone ( const StorePath * p )

Copy a StorePath.

Parameters

[in] p the path to copy

Returns: a new StorePath

◆ nix_store_path_free()

void nix_store_path_free ( StorePath * p )

Deallocate a StorePath.

Does not fail.

Parameters

[in] p the path to free

◆ nix_store_path_name()

void nix_store_path_name	(	const StorePath *	store_path,
		nix_get_string_callback	callback,
		void *	user_data )

Get the path name (e.g. "name" in /nix/store/...-name)

Parameters

[in]	store_path	the path to get the name from
[in]	callback	called with the name
[in]	user_data	arbitrary data, passed to the callback when it's called.

◆ 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 char *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

Files

Typedefs

Functions

Detailed Description

Function Documentation

◆ nix_libstore_init()

◆ nix_libstore_init_no_load_config()

◆ nix_store_copy_closure()

◆ nix_store_free()

◆ 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_path_clone()

◆ nix_store_path_free()

◆ nix_store_path_name()

◆ nix_store_real_path()

◆ nix_store_realise()