1PMEMKV_CONFIG(3) PMEMKV Programmer's Manual PMEMKV_CONFIG(3)
2
6 pmemkv_config - Configuration API for libpmemkv
7
9 #include <libpmemkv.h>
10 pmemkv_config *pmemkv_config_new(void);
12 void pmemkv_config_delete(pmemkv_config *config);
13 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 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 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 pmemkv_comparator *pmemkv_comparator_new(pmemkv_compare_function *fn, const char *name,
41 void *arg);
42 void pmemkv_comparator_delete(pmemkv_comparator *comparator);
43 For general description of pmemkv and available engines see libp‐
45 memkv(7). For description of pmemkv core API see libpmemkv(3).
46
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 • uint64_t
52 • int64_t
54 • c-style string
56 • binary data
58 • pointer to an object (with accompanying deleter function)
60 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 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 pmemkv_config *pmemkv_config_new(void);
70 Creates an instance of configuration for pmemkv database. On
71 failure, NULL is returned.
72 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 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 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 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 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 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 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 int pmemkv_config_put_oid(pmemkv_config *config, PMEMoid *oid);
119 Puts PMEMoid object to a config (for details see libpmemkv(7)).
120 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 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 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 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 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 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 Calling pmemkv_config_put_object_cb with getter implemented as:
154 void *getter(void *arg) { return arg; }
156 is equivalent to calling pmemkv_config_put_object.
158 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 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 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 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 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 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 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 Neither fn nor name can be NULL.
204 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 The comparison function should be thread safe - it can be called
211 from multiple threads.
212 On failure, NULL is returned.
214 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 To set a comparator for the database use pmemkv_config_put_object:
221 pmemkv_comparator *cmp = pmemkv_comparator_new(&compare_fn, "my_comparator", NULL);
223 pmemkv_config_put_object(cfg, "comparator", cmp, (void (*)(void *)) & pmemkv_comparator_delete);
225 ERRORS
227 Each function, except for pmemkv_config_new() and pmemkv_con‐
228 fig_delete(), returns status. Possible return values are:
229 • PMEMKV_STATUS_OK – no error
231 • PMEMKV_STATUS_UNKNOWN_ERROR – unknown error
233 • PMEMKV_STATUS_NOT_FOUND – record (or config item) not found
235 • PMEMKV_STATUS_CONFIG_PARSING_ERROR – parsing data to config failed
237 • PMEMKV_STATUS_CONFIG_TYPE_ERROR – config item has different type than
239 expected
240
242 The following examples are taken from examples/pmemkv_config_c directo‐
243 ry.
244 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 #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 #define ASSERT(expr) \
257 do { \
258 if (!(expr)) \
259 puts(pmemkv_errormsg()); \
260 assert(expr); \
261 } while (0)
262 static const uint64_t SIZE = 1024UL * 1024UL * 1024UL;
264 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 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 /* Create config */
284 pmemkv_config *config = pmemkv_config_new();
285 ASSERT(config != NULL);
286 /* 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 /* Specifies size of the database */
295 status = pmemkv_config_put_size(config, SIZE);
296 ASSERT(status == PMEMKV_STATUS_OK);
297 /* 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 /* 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 /* 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 pmemkv_config_delete(config);
318 return 0;
320 }
321 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 #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 #define ASSERT(expr) \
334 do { \
335 if (!(expr)) \
336 puts(pmemkv_errormsg()); \
337 assert(expr); \
338 } while (0)
339 /* deleter for int pointer */
341 void free_int_ptr(void *ptr)
342 {
343 free(ptr);
344 }
345 int main()
347 {
348 pmemkv_config *config = pmemkv_config_new();
349 ASSERT(config != NULL);
350 /* Put int64_t value */
352 int status = pmemkv_config_put_int64(config, "size", 1073741824);
353 ASSERT(status == PMEMKV_STATUS_OK);
354 char buffer[] = "ABC";
356 /* Put binary data stored in buffer */
358 status = pmemkv_config_put_data(config, "binary", buffer, 3);
359 ASSERT(status == PMEMKV_STATUS_OK);
360 const void *data;
362 size_t data_size;
363 /* 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 int *int_ptr = malloc(sizeof(int));
371 ASSERT(int_ptr != NULL);
372 *int_ptr = 10;
373 /* 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 int *get_int_ptr;
380 /* 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 pmemkv_config_delete(config);
387 pmemkv_config *config_from_json = pmemkv_config_new();
389 ASSERT(config_from_json != NULL);
390 /* 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 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 pmemkv_config *subconfig;
406 /* 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 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 pmemkv_config_delete(config_from_json);
418 return 0;
420 }
421
423 libpmemkv(7), libpmemkv(3) , libpmemkv_json_config(3) and
424 <https://pmem.io>
425PMEMKV - pmemkv version 1.5.0 2022-01-28 PMEMKV_CONFIG(3)