1PMEMKV_CONFIG(3) PMEMKV Programmer's Manual PMEMKV_CONFIG(3)
2
3
4
6 pmemkv_config - Configuration API for libpmemkv
7
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
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
51 • uint64_t
52
53 • int64_t
54
55 • c-style string
56
57 • binary data
58
59 • pointer 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
230 • PMEMKV_STATUS_OK – no error
231
232 • PMEMKV_STATUS_UNKNOWN_ERROR – unknown error
233
234 • PMEMKV_STATUS_NOT_FOUND – record (or config item) not found
235
236 • PMEMKV_STATUS_CONFIG_PARSING_ERROR – parsing data to config failed
237
238 • 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
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
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)