1PMEMKV_CONFIG(3)          PMEMKV Programmer's Manual          PMEMKV_CONFIG(3)
2
3
4

NAME

6       pmemkv_config - Configuration API for libpmemkv
7

SYNOPSIS

9              #include <libpmemkv.h>
10
11              pmemkv_config *pmemkv_config_new(void);
12              void pmemkv_config_delete(pmemkv_config *config);
13
14              int pmemkv_config_put_size(pmemkv_config *config, uint64_t value);
15              int pmemkv_config_put_path(pmemkv_config *config, const char *value);
16              int **deprecated** pmemkv_config_put_force_create(pmemkv_config *config,
17                                             bool value);
18              int pmemkv_config_put_create_or_error_if_exists(pmemkv_config *config, bool value);
19              int pmemkv_config_put_create_if_missing(pmemkv_config *config, bool value)
20              int pmemkv_config_put_comparator(pmemkv_config *config, pmemkv_comparator *comparator);
21              int pmemkv_config_put_oid(pmemkv_config *config, PMEMoid *oid);
22
23              int pmemkv_config_put_data(pmemkv_config *config, const char *key, const void *value,
24                          size_t value_size);
25              int pmemkv_config_put_object(pmemkv_config *config, const char *key, void *value,
26                          void (*deleter)(void *));
27              int pmemkv_config_put_object_cb(pmemkv_config *config, const char *key, void *value,
28                              void *(*getter)(void *), void (*deleter)(void *));
29              int pmemkv_config_put_uint64(pmemkv_config *config, const char *key, uint64_t value);
30              int pmemkv_config_put_int64(pmemkv_config *config, const char *key, int64_t value);
31              int pmemkv_config_put_string(pmemkv_config *config, const char *key, const char *value);
32
33              int pmemkv_config_get_data(pmemkv_config *config, const char *key, const void **value,
34                          size_t *value_size);
35              int pmemkv_config_get_object(pmemkv_config *config, const char *key, void **value);
36              int pmemkv_config_get_uint64(pmemkv_config *config, const char *key, uint64_t *value);
37              int pmemkv_config_get_int64(pmemkv_config *config, const char *key, int64_t *value);
38              int pmemkv_config_get_string(pmemkv_config *config, const char *key, const char **value);
39
40              pmemkv_comparator *pmemkv_comparator_new(pmemkv_compare_function *fn, const char *name,
41                                   void *arg);
42              void pmemkv_comparator_delete(pmemkv_comparator *comparator);
43
44       For  general  description  of  pmemkv  and  available engines see libp‐
45       memkv(7).  For description of pmemkv core API see libpmemkv(3).
46

DESCRIPTION

48       pmemkv database is configured using pmemkv_config structure.  It stores
49       mappings of keys (null-terminated strings) to values.  A value can be:
50
51uint64_t
52
53int64_t
54
55c-style string
56
57binary data
58
59pointer to an object (with accompanying deleter function)
60
61       It also delivers methods to store and read configuration items provided
62       by a user.  Once the configuration object is set (with all required pa‐
63       rameters), it can be passed to pmemkv_open() method.
64
65       List of options which are required by pmemkv database is specific to an
66       engine.  Every engine has documented all  supported  config  parameters
67       (please see libpmemkv(7) for details).
68
69       pmemkv_config *pmemkv_config_new(void);
70              Creates  an  instance  of configuration for pmemkv database.  On
71              failure, NULL is returned.
72
73       void pmemkv_config_delete(pmemkv_config *config);
74              Deletes pmemkv_config.  Should be called ONLY for configs  which
75              were not passed to pmemkv_open (as this function moves ownership
76              of the config to the database).
77
78       int pmemkv_config_put_size(pmemkv_config *config, uint64_t value);
79              Puts value to a config at key size, it’s required when  creating
80              new  database pool.  This function provides type safety for size
81              parameter.
82
83       int pmemkv_config_put_path(pmemkv_config *config, const char *value);
84              Puts value to a config at key path.  It’s a path to  a  database
85              file  or to a poolset file (see poolset(5) for details), to open
86              or create.  Note that when using poolset file, size should be 0.
87              This function provides type safety for path parameter.
88
89       int pmemkv_config_put_force_create(pmemkv_config *config, bool value);
90              It  is deprecated and kept for compatibility.  It’s an alias for
91              pmemkv_config_put_create_or_error_if_exists - use it instead.
92
93       int pmemkv_config_put_create_or_error_if_exists(pmemkv_config  *config,
94       bool value);
95              Puts  value  to a config at key create_or_error_if_exists.  This
96              flag is mutually exclusive with create_if_missing.  It works on‐
97              ly  with  engines  supporting  this  flag and it means: If true:
98              pmemkv creates the pool, unless it exists - then it  fails.   If
99              false:  pmemkv  opens the pool, unless the path does not exist -
100              then it fails.  False by default.
101
102       int  pmemkv_config_put_create_if_missing(pmemkv_config  *config,   bool
103       value)
104              Puts  value  to a config at key create_if_missing.  This flag is
105              mutually exclusive with create_or_error_if_exists.  It works on‐
106              ly  with  engines  supporting  this  flag and it means: If true:
107              pmemkv tries to open the pool and if  that  doesn’t  succeed  it
108              means  there’s (most likely) no pool to use, so it tries to cre‐
109              ate it.  If false: pmemkv opens the pool, unless the  path  does
110              not exist - then it fails.  False by default.
111
112       int pmemkv_config_put_comparator(pmemkv_config *config, pmemkv_compara‐
113       tor *comparator);
114              Puts comparator object to a config.  To create  an  instance  of
115              pmemkv_comparator   object,   pmemkv_comparator_new()   function
116              should be used.
117
118       int pmemkv_config_put_oid(pmemkv_config *config, PMEMoid *oid);
119              Puts PMEMoid object to a config (for details see libpmemkv(7)).
120
121       int pmemkv_config_put_uint64(pmemkv_config *config,  const  char  *key,
122       uint64_t value);
123              Puts uint64_t value value to pmemkv_config at key key.
124
125       int  pmemkv_config_put_int64(pmemkv_config  *config,  const  char *key,
126       int64_t value);
127              Puts int64_t value value to pmemkv_config at key key.
128
129       int pmemkv_config_put_string(pmemkv_config *config,  const  char  *key,
130       const char *value);
131              Puts  null-terminated  string  to  pmemkv_config.  The string is
132              copied to the config.
133
134       int pmemkv_config_put_data(pmemkv_config *config, const char *key, con‐
135       st void *value, size_t value_size);
136              Puts  copy  of  binary  data  pointed by value to pmemkv_config.
137              value_size specifies size of the data.
138
139       int pmemkv_config_put_object(pmemkv_config *config,  const  char  *key,
140       void *value, void (*deleter)(void *));
141              Puts  value  to pmemkv_config.  value can point to arbitrary ob‐
142              ject.  deleter parameter specifies function which will be called
143              for  value  when  the  config  is  destroyed  (using pmemkv_con‐
144              fig_delete).
145
146       int pmemkv_config_put_object_cb(pmemkv_config *config, const char *key,
147       void *value, void *(*getter)(void *), void (*deleter)(void *));
148              Extended  version  of  pmemkv_config_put_object.  It accepts one
149              additional argument - a getter callback.  This  callback  inter‐
150              prets  the  custom object (value) and returns a pointer which is
151              expected by pmemkv.
152
153              Calling pmemkv_config_put_object_cb with getter implemented as:
154
155                     void *getter(void *arg) { return arg; }
156
157              is equivalent to calling pmemkv_config_put_object.
158
159       int pmemkv_config_get_uint64(pmemkv_config *config,  const  char  *key,
160       uint64_t *value);
161              Gets  value  of  a config item with key key.  Value is copied to
162              variable pointed by value.
163
164       int pmemkv_config_get_int64(pmemkv_config  *config,  const  char  *key,
165       int64_t *value);
166              Gets  value  of  a config item with key key.  Value is copied to
167              variable pointed by value.
168
169       int pmemkv_config_get_string(pmemkv_config *config,  const  char  *key,
170       const char **value);
171              Gets  pointer  to  a  null-terminated string.  The string is not
172              copied.  After successful call value points to string stored  in
173              pmemkv_config.
174
175       int pmemkv_config_get_data(pmemkv_config *config, const char *key, con‐
176       st void **value, size_t *value_size);
177              Gets pointer to binary data.  Data is not  copied.   After  suc‐
178              cessful  call  *value points to data stored in pmemkv_config and
179              value_size holds size of the data.
180
181       int pmemkv_config_get_object(pmemkv_config *config,  const  char  *key,
182       const void **value);
183              Gets pointer to an object.  After successful call, *value points
184              to the object.
185
186       Config items stored in pmemkv_config, which were put using  a  specific
187       function  can  be  obtained only using corresponding pmemkv_config_get_
188       function (for example, config items put using  pmemkv_config_put_object
189       can  only  be obtained using pmemkv_config_get_object).  Exception from
190       this rule are  functions  for  uint64  and  int64.   If  value  put  by
191       pmemkv_config_put_int64  is  in uint64_t range it can be obtained using
192       pmemkv_config_get_uint64 and vice versa.
193
194       pmemkv_comparator  *pmemkv_comparator_new(pmemkv_compare_function  *fn,
195       const char *name, void *arg);
196              Creates  instance  of  a  comparator object.  Accepts comparison
197              function fn, name and arg. In case of persistent  engines,nameis
198              stored  within  the engine. Attempt to open a database which was
199              createad with different comparator of different name  will  fail
200              with PMEMKV_STATUS_COMPARATOR_MISMATCH.arg` is saved in the com‐
201              parator and passed to a comparison function on each invocation.
202
203              Neither fn nor name can be NULL.
204
205              fn should perform a three-way comparison.  Return values: * neg‐
206              ative  value if the first key is less than the second one * zero
207              if both keys are the same * positive value if the first  key  is
208              greater than the second one
209
210              The comparison function should be thread safe - it can be called
211              from multiple threads.
212
213              On failure, NULL is returned.
214
215       void pmemkv_comparator_delete(pmemkv_comparator *comparator);
216              Removes the comparator object.  Should be called ONLY  for  com‐
217              parators which were not put to config (as config takes ownership
218              of the comparator).
219
220       To set a comparator for the database use pmemkv_config_put_object:
221
222              pmemkv_comparator *cmp = pmemkv_comparator_new(&compare_fn, "my_comparator", NULL);
223
224              pmemkv_config_put_object(cfg, "comparator", cmp, (void (*)(void *)) & pmemkv_comparator_delete);
225
226   ERRORS
227       Each  function,  except   for   pmemkv_config_new()   and   pmemkv_con‐
228       fig_delete(), returns status.  Possible return values are:
229
230PMEMKV_STATUS_OK – no error
231
232PMEMKV_STATUS_UNKNOWN_ERROR – unknown error
233
234PMEMKV_STATUS_NOT_FOUND – record (or config item) not found
235
236PMEMKV_STATUS_CONFIG_PARSING_ERROR – parsing data to config failed
237
238PMEMKV_STATUS_CONFIG_TYPE_ERROR – config item has different type than
239         expected
240

EXAMPLE

242       The following examples are taken from examples/pmemkv_config_c directo‐
243       ry.
244
245   BASIC EXAMPLE
246       Usage  of basic config functions to set parameters based on their func‐
247       tionalities, e.g. pmemkv_config_put_path() or pmemkv_config_put_size().
248
249              #include <assert.h>
250              #include <libpmemkv.h>
251              #include <libpmemobj/pool_base.h>
252              #include <stdio.h>
253              #include <stdlib.h>
254              #include <string.h>
255
256              #define ASSERT(expr)                                                                     \
257                  do {                                                                             \
258                      if (!(expr))                                                             \
259                          puts(pmemkv_errormsg());                                         \
260                      assert(expr);                                                            \
261                  } while (0)
262
263              static const uint64_t SIZE = 1024UL * 1024UL * 1024UL;
264
265              int key_length_compare(const char *key1, size_t keybytes1, const char *key2,
266                             size_t keybytes2, void *arg)
267              {
268                  if (keybytes2 < keybytes1)
269                      return -1;
270                  else if (keybytes2 > keybytes1)
271                      return 1;
272                  else
273                      return 0;
274              }
275
276              int main(int argc, char *argv[])
277              {
278                  if (argc < 2) {
279                      fprintf(stderr, "Usage: %s file\n", argv[0]);
280                      exit(1);
281                  }
282
283                  /* Create config */
284                  pmemkv_config *config = pmemkv_config_new();
285                  ASSERT(config != NULL);
286
287                  /* Add path parameter to config. Meaning of this is dependent on chosen engine.
288                   *  E.g. if config is used with cmap engine,
289                   *  it is a path to a database file or to a poolset file. However for
290                   *  vcmap it is a path to an existing directory */
291                  int status = pmemkv_config_put_path(config, argv[1]);
292                  ASSERT(status == PMEMKV_STATUS_OK);
293
294                  /* Specifies size of the database */
295                  status = pmemkv_config_put_size(config, SIZE);
296                  ASSERT(status == PMEMKV_STATUS_OK);
297
298                  /* Specifies value of create_if_missing flag.
299                   * Alternatively, another flag - 'create_or_error_if_exists' can be set using:
300                   * `pmemkv_config_put_create_or_error_if_exists`
301                   * For differences between the two, see manpage libpmemkv(7). */
302                  status = pmemkv_config_put_create_if_missing(config, true);
303                  ASSERT(status == PMEMKV_STATUS_OK);
304
305                  /* Specifies comparator used by the engine */
306                  pmemkv_comparator *cmp =
307                      pmemkv_comparator_new(&key_length_compare, "key_length_compare", NULL);
308                  ASSERT(cmp != NULL);
309                  status = pmemkv_config_put_comparator(config, cmp);
310                  ASSERT(status == PMEMKV_STATUS_OK);
311
312                  /* Adds pointer to oid (for details see libpmemkv(7)) to the config */
313                  PMEMoid oid;
314                  status = pmemkv_config_put_oid(config, &oid);
315                  ASSERT(status == PMEMKV_STATUS_OK);
316
317                  pmemkv_config_delete(config);
318
319                  return 0;
320              }
321
322   TYPE BASED CONFIGURATION EXAMPLE
323       Usage of config functions to set and get data based on their data type,
324       e.g. pmemkv_config_put_int64() or pmemkv_config_put_object().
325
326              #include <assert.h>
327              #include <libpmemkv.h>
328              #include <libpmemkv_json_config.h>
329              #include <stdio.h>
330              #include <stdlib.h>
331              #include <string.h>
332
333              #define ASSERT(expr)                                                                     \
334                  do {                                                                             \
335                      if (!(expr))                                                             \
336                          puts(pmemkv_errormsg());                                         \
337                      assert(expr);                                                            \
338                  } while (0)
339
340              /* deleter for int pointer */
341              void free_int_ptr(void *ptr)
342              {
343                  free(ptr);
344              }
345
346              int main()
347              {
348                  pmemkv_config *config = pmemkv_config_new();
349                  ASSERT(config != NULL);
350
351                  /* Put int64_t value */
352                  int status = pmemkv_config_put_int64(config, "size", 1073741824);
353                  ASSERT(status == PMEMKV_STATUS_OK);
354
355                  char buffer[] = "ABC";
356
357                  /* Put binary data stored in buffer */
358                  status = pmemkv_config_put_data(config, "binary", buffer, 3);
359                  ASSERT(status == PMEMKV_STATUS_OK);
360
361                  const void *data;
362                  size_t data_size;
363
364                  /* Get pointer to binary data stored in config */
365                  status = pmemkv_config_get_data(config, "binary", &data, &data_size);
366                  ASSERT(status == PMEMKV_STATUS_OK);
367                  ASSERT(data_size == 3);
368                  ASSERT(((const char *)data)[0] == 'A');
369
370                  int *int_ptr = malloc(sizeof(int));
371                  ASSERT(int_ptr != NULL);
372                  *int_ptr = 10;
373
374                  /* Put pointer to dynamically allocated object, free_int_ptr is called on
375                   * pmemkv_config_delete */
376                  status = pmemkv_config_put_object(config, "int_ptr", int_ptr, &free_int_ptr);
377                  ASSERT(status == PMEMKV_STATUS_OK);
378
379                  int *get_int_ptr;
380
381                  /* Get pointer to object stored in config */
382                  status = pmemkv_config_get_object(config, "int_ptr", (void **)&get_int_ptr);
383                  ASSERT(status == PMEMKV_STATUS_OK);
384                  ASSERT(*get_int_ptr == 10);
385
386                  pmemkv_config_delete(config);
387
388                  pmemkv_config *config_from_json = pmemkv_config_new();
389                  ASSERT(config_from_json != NULL);
390
391                  /* Parse JSON and put all items found into config_from_json */
392                  status = pmemkv_config_from_json(config_from_json, "{\"path\":\"/dev/shm\",\
393                       \"size\":1073741824,\
394                       \"subconfig\":{\
395                          \"size\":1073741824\
396                          }\
397                      }");
398                  ASSERT(status == PMEMKV_STATUS_OK);
399
400                  const char *path;
401                  status = pmemkv_config_get_string(config_from_json, "path", &path);
402                  ASSERT(status == PMEMKV_STATUS_OK);
403                  ASSERT(strcmp(path, "/dev/shm") == 0);
404
405                  pmemkv_config *subconfig;
406
407                  /* Get pointer to nested configuration "subconfig" */
408                  status = pmemkv_config_get_object(config_from_json, "subconfig",
409                                    (void **)&subconfig);
410                  ASSERT(status == PMEMKV_STATUS_OK);
411
412                  size_t sub_size;
413                  status = pmemkv_config_get_uint64(subconfig, "size", &sub_size);
414                  ASSERT(status == PMEMKV_STATUS_OK);
415                  ASSERT(sub_size == 1073741824);
416
417                  pmemkv_config_delete(config_from_json);
418
419                  return 0;
420              }
421

SEE ALSO

423       libpmemkv(7),     libpmemkv(3)     ,    libpmemkv_json_config(3)    and
424       <https://pmem.io>
425
426
427
428PMEMKV - pmemkv version 1.5.0     2022-07-22                  PMEMKV_CONFIG(3)
Impressum