.\" Automatically generated by Pandoc 2.9.2.1 .\" .TH "PMEMKV_CONFIG" "3" "2021-07-26" "PMEMKV - pmemkv version 1.5.0-rc1" "PMEMKV Programmer's Manual" .hy .\" SPDX-License-Identifier: BSD-3-Clause .\" Copyright 2019-2021, Intel Corporation .SH NAME .PP \f[B]pmemkv_config\f[R] - Configuration API for libpmemkv .SH SYNOPSIS .IP .nf \f[C] #include 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); \f[R] .fi .PP For general description of pmemkv and available engines see \f[B]libpmemkv\f[R](7). For description of pmemkv core API see \f[B]libpmemkv\f[R](3). .SH DESCRIPTION .PP pmemkv database is configured using pmemkv_config structure. It stores mappings of keys (null-terminated strings) to values. A value can be: .IP \[bu] 2 \f[B]uint64_t\f[R] .IP \[bu] 2 \f[B]int64_t\f[R] .IP \[bu] 2 \f[B]c-style string\f[R] .IP \[bu] 2 \f[B]binary data\f[R] .IP \[bu] 2 \f[B]pointer to an object\f[R] (with accompanying deleter function) .PP 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 \f[I]pmemkv_open()\f[R] method. .PP List of options which are required by pmemkv database is specific to an engine. Every engine has documented all supported config parameters (please see \f[B]libpmemkv\f[R](7) for details). .TP \f[B]\f[CB]pmemkv_config *pmemkv_config_new(void);\f[B]\f[R] Creates an instance of configuration for pmemkv database. On failure, NULL is returned. .TP \f[B]\f[CB]void pmemkv_config_delete(pmemkv_config *config);\f[B]\f[R] 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). .TP \f[B]\f[CB]int pmemkv_config_put_size(pmemkv_config *config, uint64_t value);\f[B]\f[R] Puts \f[C]value\f[R] to a config at key \f[C]size\f[R], it\[cq]s required when creating new database pool. This function provides type safety for \f[B]size\f[R] parameter. .TP \f[B]\f[CB]int pmemkv_config_put_path(pmemkv_config *config, const char *value);\f[B]\f[R] Puts \f[C]value\f[R] to a config at key \f[B]path\f[R]. It\[cq]s a path to a database file or to a poolset file (see \f[B]poolset\f[R](5) for details), to open or create. Note that when using poolset file, size should be 0. This function provides type safety for \f[C]path\f[R] parameter. .TP \f[B]\f[CB]int pmemkv_config_put_force_create(pmemkv_config *config, bool value);\f[B]\f[R] It is \f[B]deprecated\f[R] and kept for compatibility. It\[cq]s an alias for \f[C]pmemkv_config_put_create_or_error_if_exists\f[R] - use it instead. .TP \f[B]\f[CB]int pmemkv_config_put_create_or_error_if_exists(pmemkv_config *config, bool value);\f[B]\f[R] Puts \f[C]value\f[R] to a config at key \f[C]create_or_error_if_exists\f[R]. This flag is mutually exclusive with \f[B]create_if_missing\f[R]. 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. .TP \f[B]\f[CB]int pmemkv_config_put_create_if_missing(pmemkv_config *config, bool value)\f[B]\f[R] Puts \f[C]value\f[R] to a config at key \f[C]create_if_missing\f[R]. This flag is mutually exclusive with \f[B]create_or_error_if_exists\f[R]. It works only with engines supporting this flag and it means: If true: pmemkv tries to open the pool and if that doesn\[cq]t succeed it means there\[cq]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. .TP \f[B]\f[CB]int pmemkv_config_put_comparator(pmemkv_config *config, pmemkv_comparator *comparator);\f[B]\f[R] Puts comparator object to a config. To create an instance of pmemkv_comparator object, \f[C]pmemkv_comparator_new()\f[R] function should be used. .TP \f[B]\f[CB]int pmemkv_config_put_oid(pmemkv_config *config, PMEMoid *oid);\f[B]\f[R] Puts PMEMoid object to a config (for details see \f[B]libpmemkv\f[R](7)). .TP \f[B]\f[CB]int pmemkv_config_put_uint64(pmemkv_config *config, const char *key, uint64_t value);\f[B]\f[R] Puts uint64_t value \f[C]value\f[R] to pmemkv_config at key \f[C]key\f[R]. .TP \f[B]\f[CB]int pmemkv_config_put_int64(pmemkv_config *config, const char *key, int64_t value);\f[B]\f[R] Puts int64_t value \f[C]value\f[R] to pmemkv_config at key \f[C]key\f[R]. .TP \f[B]\f[CB]int pmemkv_config_put_string(pmemkv_config *config, const char *key, const char *value);\f[B]\f[R] Puts null-terminated string to pmemkv_config. The string is copied to the config. .TP \f[B]\f[CB]int pmemkv_config_put_data(pmemkv_config *config, const char *key, const void *value, size_t value_size);\f[B]\f[R] Puts copy of binary data pointed by \f[C]value\f[R] to pmemkv_config. \f[C]value_size\f[R] specifies size of the data. .TP \f[B]\f[CB]int pmemkv_config_put_object(pmemkv_config *config, const char *key, void *value, void (*deleter)(void *));\f[B]\f[R] Puts \f[C]value\f[R] to pmemkv_config. \f[C]value\f[R] can point to arbitrary object. \f[C]deleter\f[R] parameter specifies function which will be called for \f[C]value\f[R] when the config is destroyed (using pmemkv_config_delete). .TP \f[B]\f[CB]int pmemkv_config_put_object_cb(pmemkv_config *config, const char *key, void *value, void *(*getter)(void *), void (*deleter)(void *));\f[B]\f[R] Extended version of pmemkv_config_put_object. It accepts one additional argument - a \f[C]getter\f[R] callback. This callback interprets the custom object (\f[C]value\f[R]) and returns a pointer which is expected by pmemkv. .RS .PP Calling pmemkv_config_put_object_cb with \f[C]getter\f[R] implemented as: .IP .nf \f[C] void *getter(void *arg) { return arg; } \f[R] .fi .PP is equivalent to calling pmemkv_config_put_object. .RE .TP \f[B]\f[CB]int pmemkv_config_get_uint64(pmemkv_config *config, const char *key, uint64_t *value);\f[B]\f[R] Gets value of a config item with key \f[C]key\f[R]. Value is copied to variable pointed by \f[C]value\f[R]. .TP \f[B]\f[CB]int pmemkv_config_get_int64(pmemkv_config *config, const char *key, int64_t *value);\f[B]\f[R] Gets value of a config item with key \f[C]key\f[R]. Value is copied to variable pointed by \f[C]value\f[R]. .TP \f[B]\f[CB]int pmemkv_config_get_string(pmemkv_config *config, const char *key, const char **value);\f[B]\f[R] Gets pointer to a null-terminated string. The string is not copied. After successful call \f[C]value\f[R] points to string stored in pmemkv_config. .TP \f[B]\f[CB]int pmemkv_config_get_data(pmemkv_config *config, const char *key, const void **value, size_t *value_size);\f[B]\f[R] Gets pointer to binary data. Data is not copied. After successful call \f[C]*value\f[R] points to data stored in pmemkv_config and \f[C]value_size\f[R] holds size of the data. .TP \f[B]\f[CB]int pmemkv_config_get_object(pmemkv_config *config, const char *key, const void **value);\f[B]\f[R] Gets pointer to an object. After successful call, \f[C]*value\f[R] points to the object. .PP 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. .TP \f[B]\f[CB]pmemkv_comparator *pmemkv_comparator_new(pmemkv_compare_function *fn, const char *name, void *arg);\f[B]\f[R] Creates instance of a comparator object. Accepts comparison function \f[C]fn\f[R], \f[C]name\f[R] and \f[C]arg. In case of persistent engines,\f[R]name\f[C]is 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.\f[R]arg\[ga] is saved in the comparator and passed to a comparison function on each invocation. .RS .PP Neither \f[C]fn\f[R] nor \f[C]name\f[R] can be NULL. .PP \f[C]fn\f[R] should perform a three-way comparison. Return values: * negative value if the first key is less than the second one * zero if both keys are the same * positive value if the first key is greater than the second one .PP The comparison function should be thread safe - it can be called from multiple threads. .PP On failure, NULL is returned. .RE .TP \f[B]\f[CB]void pmemkv_comparator_delete(pmemkv_comparator *comparator);\f[B]\f[R] Removes the comparator object. Should be called ONLY for comparators which were not put to config (as config takes ownership of the comparator). .PP To set a comparator for the database use \f[C]pmemkv_config_put_object\f[R]: .IP .nf \f[C] pmemkv_comparator *cmp = pmemkv_comparator_new(&compare_fn, \[dq]my_comparator\[dq], NULL); pmemkv_config_put_object(cfg, \[dq]comparator\[dq], cmp, (void (*)(void *)) & pmemkv_comparator_delete); \f[R] .fi .SS ERRORS .PP Each function, except for \f[I]pmemkv_config_new()\f[R] and \f[I]pmemkv_config_delete()\f[R], returns status. Possible return values are: .IP \[bu] 2 \f[B]PMEMKV_STATUS_OK\f[R] \[en] no error .IP \[bu] 2 \f[B]PMEMKV_STATUS_UNKNOWN_ERROR\f[R] \[en] unknown error .IP \[bu] 2 \f[B]PMEMKV_STATUS_NOT_FOUND\f[R] \[en] record (or config item) not found .IP \[bu] 2 \f[B]PMEMKV_STATUS_CONFIG_PARSING_ERROR\f[R] \[en] parsing data to config failed .IP \[bu] 2 \f[B]PMEMKV_STATUS_CONFIG_TYPE_ERROR\f[R] \[en] config item has different type than expected .SH EXAMPLE .PP The following examples are taken from \f[C]examples/pmemkv_config_c\f[R] directory. .SS BASIC EXAMPLE .PP Usage of basic config functions to set parameters based on their functionalities, e.g.\ \f[C]pmemkv_config_put_path()\f[R] or \f[C]pmemkv_config_put_size()\f[R]. .IP .nf \f[C] #include #include #include #include #include #include #define ASSERT(expr) \[rs] do { \[rs] if (!(expr)) \[rs] puts(pmemkv_errormsg()); \[rs] assert(expr); \[rs] } 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, \[dq]Usage: %s file\[rs]n\[dq], argv[0]); exit(1); } /* Create config */ pmemkv_config *config = pmemkv_config_new(); ASSERT(config != NULL); /* 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); /* Specifies size of the database */ status = pmemkv_config_put_size(config, SIZE); ASSERT(status == PMEMKV_STATUS_OK); /* Specifies value of create_if_missing flag. * Alternatively, another flag - \[aq]create_or_error_if_exists\[aq] can be set using: * \[ga]pmemkv_config_put_create_or_error_if_exists\[ga] * For differences between the two, see manpage libpmemkv(7). */ status = pmemkv_config_put_create_if_missing(config, true); ASSERT(status == PMEMKV_STATUS_OK); /* Specifies comparator used by the engine */ pmemkv_comparator *cmp = pmemkv_comparator_new(&key_length_compare, \[dq]key_length_compare\[dq], NULL); ASSERT(cmp != NULL); status = pmemkv_config_put_comparator(config, cmp); ASSERT(status == PMEMKV_STATUS_OK); /* Adds pointer to oid (for details see libpmemkv(7)) to the config */ PMEMoid oid; status = pmemkv_config_put_oid(config, &oid); ASSERT(status == PMEMKV_STATUS_OK); pmemkv_config_delete(config); return 0; } \f[R] .fi .SS TYPE BASED CONFIGURATION EXAMPLE .PP Usage of config functions to set and get data based on their data type, e.g.\ \f[C]pmemkv_config_put_int64()\f[R] or \f[C]pmemkv_config_put_object()\f[R]. .IP .nf \f[C] #include #include #include #include #include #include #define ASSERT(expr) \[rs] do { \[rs] if (!(expr)) \[rs] puts(pmemkv_errormsg()); \[rs] assert(expr); \[rs] } 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); /* Put int64_t value */ int status = pmemkv_config_put_int64(config, \[dq]size\[dq], 1073741824); ASSERT(status == PMEMKV_STATUS_OK); char buffer[] = \[dq]ABC\[dq]; /* Put binary data stored in buffer */ status = pmemkv_config_put_data(config, \[dq]binary\[dq], 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, \[dq]binary\[dq], &data, &data_size); ASSERT(status == PMEMKV_STATUS_OK); ASSERT(data_size == 3); ASSERT(((const char *)data)[0] == \[aq]A\[aq]); 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, \[dq]int_ptr\[dq], 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, \[dq]int_ptr\[dq], (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, \[dq]{\[rs]\[dq]path\[rs]\[dq]:\[rs]\[dq]/dev/shm\[rs]\[dq],\[rs] \[rs]\[dq]size\[rs]\[dq]:1073741824,\[rs] \[rs]\[dq]subconfig\[rs]\[dq]:{\[rs] \[rs]\[dq]size\[rs]\[dq]:1073741824\[rs] }\[rs] }\[dq]); ASSERT(status == PMEMKV_STATUS_OK); const char *path; status = pmemkv_config_get_string(config_from_json, \[dq]path\[dq], &path); ASSERT(status == PMEMKV_STATUS_OK); ASSERT(strcmp(path, \[dq]/dev/shm\[dq]) == 0); pmemkv_config *subconfig; /* Get pointer to nested configuration \[dq]subconfig\[dq] */ status = pmemkv_config_get_object(config_from_json, \[dq]subconfig\[dq], (void **)&subconfig); ASSERT(status == PMEMKV_STATUS_OK); size_t sub_size; status = pmemkv_config_get_uint64(subconfig, \[dq]size\[dq], &sub_size); ASSERT(status == PMEMKV_STATUS_OK); ASSERT(sub_size == 1073741824); pmemkv_config_delete(config_from_json); return 0; } \f[R] .fi .SH SEE ALSO .PP \f[B]libpmemkv\f[R](7), \f[B]libpmemkv\f[R](3) , \f[B]libpmemkv_json_config\f[R](3) and \f[B]\f[R]