Provided by: libpmemkv-dev_1.1-1_amd64 bug

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>