Nix 2.29.1
Nix, the purely functional package manager: C API (experimental)
 
Loading...
Searching...
No Matches
libstore

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.
 
Storenix_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"
 
StorePathnix_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)
 
StorePathnix_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]contextOptional, 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]contextOptional, stores error information
[in]srcStorenix source store reference
[in]dstStorenix destination store reference
[in]pathPath 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]storethe 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]contextOptional, stores error information
[in]storenix store reference
[in]callbackCalled with the URI.
[in]user_dataoptional, 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]contextOptional, stores error information
[in]storenix store reference
[in]callbackCalled with the URI.
[in]user_dataoptional, 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]contextOptional, stores error information
[in]storenix store reference
[in]callbackCalled with the version.
[in]user_dataoptional, 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]contextOptional, stores error information
[in]storeNix Store reference
[in]pathPath 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]contextOptional, 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]contextOptional, stores error information
[in]storenix store reference
[in]pathPath 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]pthe 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]pthe 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_paththe path to get the name from
[in]callbackcalled with the name
[in]user_dataarbitrary 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]contextOptional, stores error information
[in]storenix store reference
[in]paththe path to get the real path from
[in]callbackcalled with the real path
[in]user_dataarbitrary 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]contextOptional, stores error information
[in]storeNix Store reference
[in]pathPath to build
[in]userdatadata to pass to every callback invocation
[in]callbackcalled for every realised output