NAME
SYNOPSIS
DESCRIPTION
ERRORS
EXAMPLE
SEE ALSO
pmemkv_config - Configuration API for libpmemkv
#include <libpmemkv.h>
pmemkv_config *pmemkv_config_new(void);
void pmemkv_config_delete(pmemkv_config *config);
int pmemkv_config_put_size(pmemkv_config config, uint64_t value);
int pmemkv_config_put_path(pmemkv_config config, const char value);
int deprecated pmemkv_config_put_force_create(pmemkv_config config,
bool value);
int pmemkv_config_put_create_or_error_if_exists(pmemkv_config config, bool value);
int pmemkv_config_put_create_if_missing(pmemkv_config config, bool value)
int pmemkv_config_put_comparator(pmemkv_config config, pmemkv_comparator comparator);
int pmemkv_config_put_oid(pmemkv_config config, PMEMoid oid);
int pmemkv_config_put_data(pmemkv_config config, const char key, const void value,
size_t value_size);
int pmemkv_config_put_object(pmemkv_config config, const char key, void value,
void (deleter)(void ));
int pmemkv_config_put_object_cb(pmemkv_config config, const char key, void value,
void (getter)(void ), void (deleter)(void ));
int pmemkv_config_put_uint64(pmemkv_config config, const char key, uint64_t value);
int pmemkv_config_put_int64(pmemkv_config config, const char key, int64_t value);
int pmemkv_config_put_string(pmemkv_config config, const char key, const char *value);
int pmemkv_config_get_data(pmemkv_config config, const char key, const void value,
size_t value_size);
int pmemkv_config_get_object(pmemkv_config config, const char *key, void value);
int pmemkv_config_get_uint64(pmemkv_config config, const char key, uint64_t value);
int pmemkv_config_get_int64(pmemkv_config config, const char key, int64_t value);
int pmemkv_config_get_string(pmemkv_config config, const char key, const char **value);
pmemkv_comparator pmemkv_comparator_new(pmemkv_compare_function fn, const char name,
void arg);
void pmemkv_comparator_delete(pmemkv_comparator *comparator);
For general description of pmemkv and available engines see libpmemkv(7). For description of pmemkv core API see libpmemkv(3).
pmemkv database is configured using pmemkv_config structure. It stores mappings of keys (null-terminated strings) to values. A value can be:
It also delivers methods to store and read configuration items provided by a user. Once the configuration object is set (with all required parameters), it can be passed to pmemkv_open() method.
List of options which are required by pmemkv database is specific to an engine. Every engine has documented all supported config parameters (please see libpmemkv(7) for details).
pmemkv_config *pmemkv_config_new(void);
Creates an instance of configuration for pmemkv database. On failure, NULL is returned.
void pmemkv_config_delete(pmemkv_config *config);
Deletes pmemkv_config. Should be called ONLY for configs which were not passed to pmemkv_open (as this function moves ownership of the config to the database).
int pmemkv_config_put_size(pmemkv_config *config, uint64_t value);
Puts value
to a config at key size
, it’s required when creating
new database pool. This function provides type safety for size parameter.
int pmemkv_config_put_path(pmemkv_config *config, const char *value);
Puts value
to a config at key path. It’s a path to a database file
or to a poolset file (see poolset(5) for details), to open or create.
Note that when using poolset file, size should be 0.
This function provides type safety for path
parameter.
int pmemkv_config_put_force_create(pmemkv_config *config, bool value);
It is deprecated and kept for compatibility. It’s an alias for
pmemkv_config_put_create_or_error_if_exists
- use it instead.
int pmemkv_config_put_create_or_error_if_exists(pmemkv_config *config, bool value);
Puts value
to a config at key create_or_error_if_exists
. This flag is mutually exclusive
with create_if_missing. It works only with engines supporting this flag and it means:
If true: pmemkv creates the pool, unless it exists - then it fails.
If false: pmemkv opens the pool, unless the path does not exist - then it fails.
False by default.
int pmemkv_config_put_create_if_missing(pmemkv_config *config, bool value)
Puts value
to a config at key create_if_missing
. This flag is mutually exclusive with
create_or_error_if_exists. It works only with engines supporting this flag and it means:
If true: pmemkv tries to open the pool and if that doesn’t succeed
it means there’s (most likely) no pool to use, so it tries to create it.
If false: pmemkv opens the pool, unless the path does not exist - then it fails.
False by default.
int pmemkv_config_put_comparator(pmemkv_config *config, pmemkv_comparator *comparator);
Puts comparator object to a config. To create an instance of pmemkv_comparator object,
pmemkv_comparator_new()
function should be used.
int pmemkv_config_put_oid(pmemkv_config *config, PMEMoid *oid);
Puts PMEMoid object to a config (for details see libpmemkv(7)).
int pmemkv_config_put_uint64(pmemkv_config *config, const char *key, uint64_t value);
Puts uint64_t value value
to pmemkv_config at key key
.
int pmemkv_config_put_int64(pmemkv_config *config, const char *key, int64_t value);
Puts int64_t value value
to pmemkv_config at key key
.
int pmemkv_config_put_string(pmemkv_config *config, const char *key, const char *value);
Puts null-terminated string to pmemkv_config. The string is copied to the config.
int pmemkv_config_put_data(pmemkv_config *config, const char *key, const void *value, size_t value_size);
Puts copy of binary data pointed by value
to pmemkv_config. value_size
specifies size of the data.
int pmemkv_config_put_object(pmemkv_config *config, const char *key, void *value, void (*deleter)(void *));
Puts value
to pmemkv_config. value
can point to arbitrary object.
deleter
parameter specifies function which will be called for value
when the config is destroyed (using pmemkv_config_delete).
int pmemkv_config_put_object_cb(pmemkv_config *config, const char *key, void *value, void *(*getter)(void *), void (*deleter)(void *));
Extended version of pmemkv_config_put_object. It accepts one additional argument -
a getter
callback. This callback interprets the custom object (value
) and returns
a pointer which is expected by pmemkv.
Calling pmemkv_config_put_object_cb with getter
implemented as:
void *getter(void *arg) { return arg; }
is equivalent to calling pmemkv_config_put_object.
int pmemkv_config_get_uint64(pmemkv_config *config, const char *key, uint64_t *value);
Gets value of a config item with key key
. Value is copied to variable pointed by
value
.
int pmemkv_config_get_int64(pmemkv_config *config, const char *key, int64_t *value);
Gets value of a config item with key key
. Value is copied to variable pointed by
value
.
int pmemkv_config_get_string(pmemkv_config *config, const char *key, const char **value);
Gets pointer to a null-terminated string. The string is not copied. After successful call
value
points to string stored in pmemkv_config.
int pmemkv_config_get_data(pmemkv_config *config, const char *key, const void **value, size_t *value_size);
Gets pointer to binary data. Data is not copied. After successful call
*value
points to data stored in pmemkv_config and value_size
holds size of the data.
int pmemkv_config_get_object(pmemkv_config *config, const char *key, const void **value);
Gets pointer to an object. After successful call, *value
points to the object.
Config items stored in pmemkv_config, which were put using a specific function can be obtained only using corresponding pmemkv_config_get_ function (for example, config items put using pmemkv_config_put_object can only be obtained using pmemkv_config_get_object). Exception from this rule are functions for uint64 and int64. If value put by pmemkv_config_put_int64 is in uint64_t range it can be obtained using pmemkv_config_get_uint64 and vice versa.
pmemkv_comparator *pmemkv_comparator_new(pmemkv_compare_function *fn, const char *name, void *arg);
Creates instance of a comparator object. Accepts comparison function fn
,
name
and arg. In case of persistent engines,
nameis stored within the engine. Attempt to open a database which was createad with different comparator of different name will fail with PMEMKV_STATUS_COMPARATOR_MISMATCH.
arg` is saved in the comparator and passed to a
comparison function on each invocation.
Neither fn
nor name
can be NULL.
fn
should perform a three-way comparison. Return values:
The comparison function should be thread safe - it can be called from multiple threads.
On failure, NULL is returned.
void pmemkv_comparator_delete(pmemkv_comparator *comparator);
Removes the comparator object. Should be called ONLY for comparators which were not put to config (as config takes ownership of the comparator).
To set a comparator for the database use pmemkv_config_put_object
:
pmemkv_comparator *cmp = pmemkv_comparator_new(&compare_fn, "my_comparator", NULL);
pmemkv_config_put_object(cfg, "comparator", cmp, (void ()(void )) & pmemkv_comparator_delete);
Each function, except for pmemkv_config_new() and pmemkv_config_delete(), returns status. Possible return values are:
The following examples are taken from examples/pmemkv_config_c
directory.
Usage of basic config functions to set parameters based on their functionalities, e.g. pmemkv_config_put_path()
or pmemkv_config_put_size()
.
#include <assert.h>
#include <libpmemkv.h>
#include <libpmemobj/pool_base.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#define ASSERT(expr) \
do { \
if (!(expr)) \
puts(pmemkv_errormsg()); \
assert(expr); \
} while (0)
static const uint64_t SIZE = 1024UL * 1024UL * 1024UL;
int key_length_compare(const char key1, size_t keybytes1, const char key2,
size_t keybytes2, void *arg)
{
if (keybytes2 < keybytes1)
return -1;
else if (keybytes2 > keybytes1)
return 1;
else
return 0;
}
int main(int argc, char *argv[])
{
if (argc < 2) {
fprintf(stderr, "Usage: %s file\n", argv[0]);
exit(1);
}
<span style="color:#75715e">/* Create config */</span>
pmemkv_config <span style="color:#f92672">*</span>config <span style="color:#f92672">=</span> pmemkv_config_new();
ASSERT(config <span style="color:#f92672">!=</span> NULL);
<span style="color:#75715e">/* Add path parameter to config. Meaning of this is dependent on chosen engine.
* E.g. if config is used with cmap engine,
* it is a path to a database file or to a poolset file. However for
* vcmap it is a path to an existing directory */
int status = pmemkv_config_put_path(config, argv[1]);
ASSERT(status == PMEMKV_STATUS_OK);
<span style="color:#75715e">/* Specifies size of the database */</span>
status <span style="color:#f92672">=</span> pmemkv_config_put_size(config, SIZE);
ASSERT(status <span style="color:#f92672">==</span> PMEMKV_STATUS_OK);
<span style="color:#75715e">/* Specifies value of create_if_missing flag.
* Alternatively, another flag - 'create_or_error_if_exists' can be set using:
* pmemkv_config_put_create_or_error_if_exists
* For differences between the two, see manpage libpmemkv(7). */
status = pmemkv_config_put_create_if_missing(config, true);
ASSERT(status == PMEMKV_STATUS_OK);
<span style="color:#75715e">/* Specifies comparator used by the engine */</span>
pmemkv_comparator <span style="color:#f92672">*</span>cmp <span style="color:#f92672">=</span>
pmemkv_comparator_new(<span style="color:#f92672">&</span>key_length_compare, <span style="color:#e6db74">"key_length_compare"</span>, NULL);
ASSERT(cmp <span style="color:#f92672">!=</span> NULL);
status <span style="color:#f92672">=</span> pmemkv_config_put_comparator(config, cmp);
ASSERT(status <span style="color:#f92672">==</span> PMEMKV_STATUS_OK);
<span style="color:#75715e">/* Adds pointer to oid (for details see libpmemkv(7)) to the config */</span>
PMEMoid oid;
status <span style="color:#f92672">=</span> pmemkv_config_put_oid(config, <span style="color:#f92672">&</span>oid);
ASSERT(status <span style="color:#f92672">==</span> PMEMKV_STATUS_OK);
pmemkv_config_delete(config);
<span style="color:#66d9ef">return</span> <span style="color:#ae81ff">0</span>;
}
Usage of config functions to set and get data based on their data type, e.g. pmemkv_config_put_int64()
or pmemkv_config_put_object()
.
#include <assert.h>
#include <libpmemkv.h>
#include <libpmemkv_json_config.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#define ASSERT(expr) \
do { \
if (!(expr)) \
puts(pmemkv_errormsg()); \
assert(expr); \
} while (0)
/* deleter for int pointer */
void free_int_ptr(void *ptr)
{
free(ptr);
}
int main()
{
pmemkv_config *config = pmemkv_config_new();
ASSERT(config != NULL);
<span style="color:#75715e">/* Put int64_t value */</span>
<span style="color:#66d9ef">int</span> status <span style="color:#f92672">=</span> pmemkv_config_put_int64(config, <span style="color:#e6db74">"size"</span>, <span style="color:#ae81ff">1073741824</span>);
ASSERT(status <span style="color:#f92672">==</span> PMEMKV_STATUS_OK);
<span style="color:#66d9ef">char</span> buffer[] <span style="color:#f92672">=</span> <span style="color:#e6db74">"ABC"</span>;
<span style="color:#75715e">/* Put binary data stored in buffer */</span>
status <span style="color:#f92672">=</span> pmemkv_config_put_data(config, <span style="color:#e6db74">"binary"</span>, buffer, <span style="color:#ae81ff">3</span>);
ASSERT(status <span style="color:#f92672">==</span> PMEMKV_STATUS_OK);
<span style="color:#66d9ef">const</span> <span style="color:#66d9ef">void</span> <span style="color:#f92672">*</span>data;
size_t data_size;
<span style="color:#75715e">/* Get pointer to binary data stored in config */</span>
status <span style="color:#f92672">=</span> pmemkv_config_get_data(config, <span style="color:#e6db74">"binary"</span>, <span style="color:#f92672">&</span>data, <span style="color:#f92672">&</span>data_size);
ASSERT(status <span style="color:#f92672">==</span> PMEMKV_STATUS_OK);
ASSERT(data_size <span style="color:#f92672">==</span> <span style="color:#ae81ff">3</span>);
ASSERT(((<span style="color:#66d9ef">const</span> <span style="color:#66d9ef">char</span> <span style="color:#f92672">*</span>)data)[<span style="color:#ae81ff">0</span>] <span style="color:#f92672">==</span> <span style="color:#e6db74">'A'</span>);
<span style="color:#66d9ef">int</span> <span style="color:#f92672">*</span>int_ptr <span style="color:#f92672">=</span> malloc(<span style="color:#66d9ef">sizeof</span>(<span style="color:#66d9ef">int</span>));
ASSERT(int_ptr <span style="color:#f92672">!=</span> NULL);
<span style="color:#f92672">*</span>int_ptr <span style="color:#f92672">=</span> <span style="color:#ae81ff">10</span>;
<span style="color:#75715e">/* Put pointer to dynamically allocated object, free_int_ptr is called on
* pmemkv_config_delete */
status = pmemkv_config_put_object(config, "int_ptr", int_ptr, &free_int_ptr);
ASSERT(status == PMEMKV_STATUS_OK);
<span style="color:#66d9ef">int</span> <span style="color:#f92672">*</span>get_int_ptr;
<span style="color:#75715e">/* Get pointer to object stored in config */</span>
status <span style="color:#f92672">=</span> pmemkv_config_get_object(config, <span style="color:#e6db74">"int_ptr"</span>, (<span style="color:#66d9ef">void</span> <span style="color:#f92672">**</span>)<span style="color:#f92672">&</span>get_int_ptr);
ASSERT(status <span style="color:#f92672">==</span> PMEMKV_STATUS_OK);
ASSERT(<span style="color:#f92672">*</span>get_int_ptr <span style="color:#f92672">==</span> <span style="color:#ae81ff">10</span>);
pmemkv_config_delete(config);
pmemkv_config <span style="color:#f92672">*</span>config_from_json <span style="color:#f92672">=</span> pmemkv_config_new();
ASSERT(config_from_json <span style="color:#f92672">!=</span> NULL);
<span style="color:#75715e">/* Parse JSON and put all items found into config_from_json */</span>
status <span style="color:#f92672">=</span> pmemkv_config_from_json(config_from_json, <span style="color:#e6db74">"{</span><span style="color:#ae81ff">\"</span><span style="color:#e6db74">path</span><span style="color:#ae81ff">\"</span><span style="color:#e6db74">:</span><span style="color:#ae81ff">\"</span><span style="color:#e6db74">/dev/shm</span><span style="color:#ae81ff">\"</span><span style="color:#e6db74">,\
"size":1073741824,
"subconfig":{
"size":1073741824
}
}");
ASSERT(status == PMEMKV_STATUS_OK);
<span style="color:#66d9ef">const</span> <span style="color:#66d9ef">char</span> <span style="color:#f92672">*</span>path;
status <span style="color:#f92672">=</span> pmemkv_config_get_string(config_from_json, <span style="color:#e6db74">"path"</span>, <span style="color:#f92672">&</span>path);
ASSERT(status <span style="color:#f92672">==</span> PMEMKV_STATUS_OK);
ASSERT(strcmp(path, <span style="color:#e6db74">"/dev/shm"</span>) <span style="color:#f92672">==</span> <span style="color:#ae81ff">0</span>);
pmemkv_config <span style="color:#f92672">*</span>subconfig;
<span style="color:#75715e">/* Get pointer to nested configuration "subconfig" */</span>
status <span style="color:#f92672">=</span> pmemkv_config_get_object(config_from_json, <span style="color:#e6db74">"subconfig"</span>,
(<span style="color:#66d9ef">void</span> <span style="color:#f92672">**</span>)<span style="color:#f92672">&</span>subconfig);
ASSERT(status <span style="color:#f92672">==</span> PMEMKV_STATUS_OK);
size_t sub_size;
status <span style="color:#f92672">=</span> pmemkv_config_get_uint64(subconfig, <span style="color:#e6db74">"size"</span>, <span style="color:#f92672">&</span>sub_size);
ASSERT(status <span style="color:#f92672">==</span> PMEMKV_STATUS_OK);
ASSERT(sub_size <span style="color:#f92672">==</span> <span style="color:#ae81ff">1073741824</span>);
pmemkv_config_delete(config_from_json);
<span style="color:#66d9ef">return</span> <span style="color:#ae81ff">0</span>;
}
libpmemkv(7), libpmemkv(3) , libpmemkv_json_config(3) and https://pmem.io
The contents of this web site and the associated GitHub repositories are BSD-licensed open source.