Provided by: libpmemkv-dev_1.1-1_amd64
NAME
pmemkv_config - Configuration API for libpmemkv
SYNOPSIS
#include <libpmemkv.h> pmemkv_config *pmemkv_config_new(void); void pmemkv_config_delete(pmemkv_config *config); 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_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); For general description of pmemkv and available engines see libpmemkv(7). For description of pmemkv core API see libpmemkv(3).
DESCRIPTION
pmemkv database is configured using pmemkv_config structure. It stores mappings of keys (null-terminated strings) to values. A value can be: • uint64_t • int64_t • c-style string • binary data • pointer to an object (with accompanying deleter function) 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_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_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. ERRORS Each function, except for pmemkv_config_new() and pmemkv_config_delete(), returns status. Possible return values are: • PMEMKV_STATUS_OK – no error • PMEMKV_STATUS_UNKNOWN_ERROR – unknown error • PMEMKV_STATUS_NOT_FOUND – record (or config item) not found • PMEMKV_STATUS_CONFIG_PARSING_ERROR – parsing data to config failed • PMEMKV_STATUS_CONFIG_TYPE_ERROR – config item has different type than expected
EXAMPLE
The following example is taken from examples/pmemkv_config_c/pmemkv_config.c. #include <assert.h> #include <libpmemkv.h> #include <libpmemkv_json_config.h> #include <stdlib.h> #include <string.h> /* deleter for int pointer */ void free_int_ptr(void *ptr) { free(ptr); } int main() { pmemkv_config *config = pmemkv_config_new(); assert(config != NULL); /* Put int64_t value */ int status = pmemkv_config_put_int64(config, "size", 1073741824); assert(status == PMEMKV_STATUS_OK); char buffer[] = "ABC"; /* Put binary data stored in buffer */ status = pmemkv_config_put_data(config, "binary", buffer, 3); assert(status == PMEMKV_STATUS_OK); const void *data; size_t data_size; /* Get pointer to binary data stored in config */ status = pmemkv_config_get_data(config, "binary", &data, &data_size); assert(status == PMEMKV_STATUS_OK); assert(data_size == 3); assert(((const char *)data)[0] == 'A'); int *int_ptr = malloc(sizeof(int)); assert(int_ptr != NULL); *int_ptr = 10; /* 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); int *get_int_ptr; /* Get pointer to object stored in config */ status = pmemkv_config_get_object(config, "int_ptr", (void **)&get_int_ptr); assert(status == PMEMKV_STATUS_OK); assert(*get_int_ptr == 10); pmemkv_config_delete(config); pmemkv_config *config_from_json = pmemkv_config_new(); assert(config_from_json != NULL); /* Parse JSON and put all items found into config_from_json */ status = pmemkv_config_from_json(config_from_json, "{\"path\":\"/dev/shm\",\ \"size\":1073741824,\ \"subconfig\":{\ \"size\":1073741824\ }\ }"); assert(status == PMEMKV_STATUS_OK); const char *path; status = pmemkv_config_get_string(config_from_json, "path", &path); assert(status == PMEMKV_STATUS_OK); assert(strcmp(path, "/dev/shm") == 0); pmemkv_config *subconfig; /* Get pointer to nested configuration "subconfig" */ status = pmemkv_config_get_object(config_from_json, "subconfig", (void **)&subconfig); assert(status == PMEMKV_STATUS_OK); size_t sub_size; status = pmemkv_config_get_uint64(subconfig, "size", &sub_size); assert(status == PMEMKV_STATUS_OK); assert(sub_size == 1073741824); pmemkv_config_delete(config_from_json); return 0; }
SEE ALSO
libpmemkv(7), libpmemkv(3) , libpmemkv_json_config(3) and <https://pmem.io>