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_data(pmemkv_config *config, const char *key, const void *value,
14 size_t value_size);
15 int pmemkv_config_put_object(pmemkv_config *config, const char *key, void *value,
16 void (*deleter)(void *));
17 int pmemkv_config_put_uint64(pmemkv_config *config, const char *key, uint64_t value);
18 int pmemkv_config_put_int64(pmemkv_config *config, const char *key, int64_t value);
19 int pmemkv_config_put_string(pmemkv_config *config, const char *key, const char *value);
20 int pmemkv_config_get_data(pmemkv_config *config, const char *key, const void **value,
21 size_t *value_size);
22 int pmemkv_config_get_object(pmemkv_config *config, const char *key, void **value);
23 int pmemkv_config_get_uint64(pmemkv_config *config, const char *key, uint64_t *value);
24 int pmemkv_config_get_int64(pmemkv_config *config, const char *key, int64_t *value);
25 int pmemkv_config_get_string(pmemkv_config *config, const char *key, const char **value);
26 For general description of pmemkv and available engines see libp‐
28 memkv(7). For description of pmemkv core API see libpmemkv(3).
29
31 pmemkv database is configured using pmemkv_config structure. It stores
32 mappings of keys (null-terminated strings) to values. A value can be:
33 · uint64_t
35 · int64_t
37 · c-style string
39 · binary data
41 · pointer to an object (with accompanying deleter function)
43 It also delivers methods to store and read configuration items provided
45 by a user. Once the configuration object is set (with all required pa‐
46 rameters), it can be passed to pmemkv_open() method.
47 List of options which are required by pmemkv database is specific to an
49 engine. Every engine has documented all supported config parameters
50 (please see libpmemkv(7) for details).
51 pmemkv_config *pmemkv_config_new(void);
53 Creates an instance of configuration for pmemkv database.
54 On failure, NULL is returned.
56 void pmemkv_config_delete(pmemkv_config *config);
58 Deletes pmemkv_config. Should be called ONLY for configs which
59 were not passed to pmemkv_open (as this function moves ownership
60 of the config to the database).
61 int pmemkv_config_put_uint64(pmemkv_config *config, const char *key,
63 uint64_t value);
64 Puts uint64_t value value to pmemkv_config at key key.
65 int pmemkv_config_put_int64(pmemkv_config *config, const char *key,
67 int64_t value);
68 Puts int64_t value value to pmemkv_config at key key.
69 int pmemkv_config_put_string(pmemkv_config *config, const char *key,
71 const char *value);
72 Puts null-terminated string to pmemkv_config. The string is
73 copied to the config.
74 int pmemkv_config_put_data(pmemkv_config *config, const char *key, con‐
76 st void *value, size_t value_size);
77 Puts copy of binary data pointed by value to pmemkv_config.
78 value_size specifies size of the data.
79 int pmemkv_config_put_object(pmemkv_config *config, const char *key,
81 void *value, void (*deleter)(void *));
82 Puts value to pmemkv_config. value can point to arbitrary ob‐
83 ject. deleter parameter specifies function which will be called
84 for value when the config is destroyed (using pmemkv_con‐
85 fig_delete).
86 int pmemkv_config_get_uint64(pmemkv_config *config, const char *key,
88 uint64_t *value);
89 Gets value of a config item with key key. Value is copied to
90 variable pointed by value.
91 int pmemkv_config_get_int64(pmemkv_config *config, const char *key,
93 int64_t *value);
94 Gets value of a config item with key key. Value is copied to
95 variable pointed by value.
96 int pmemkv_config_get_string(pmemkv_config *config, const char *key,
98 const char **value);
99 Gets pointer to a null-terminated string. The string is not
100 copied. After successful call value points to string stored in
101 pmemkv_config.
102 int pmemkv_config_get_data(pmemkv_config *config, const char *key, con‐
104 st void **value, size_t *value_size);
105 Gets pointer to binary data. Data is not copied. After suc‐
106 cessful call *value points to data stored in pmemkv_config and
107 value_size holds size of the data.
108 int pmemkv_config_get_object(pmemkv_config *config, const char *key,
110 const void **value);
111 Gets pointer to an object. After successful call, *value points
112 to the object.
113 Config items stored in pmemkv_config, which were put using a specific
115 function can be obtained only using corresponding pmemkv_config_get_
116 function (for example, config items put using pmemkv_config_put_object
117 can only be obtained using pmemkv_config_get_object). Exception from
118 this rule are functions for uint64 and int64. If value put by
119 pmemkv_config_put_int64 is in uint64_t range it can be obtained using
120 pmemkv_config_get_uint64 and vice versa.
121 ERRORS
123 Each function, except for pmemkv_config_new() and pmemkv_con‐
124 fig_delete(), returns status. Possible return values are:
125 · PMEMKV_STATUS_OK – no error
127 · PMEMKV_STATUS_UNKNOWN_ERROR – unknown error
129 · PMEMKV_STATUS_NOT_FOUND – record (or config item) not found
131 · PMEMKV_STATUS_CONFIG_PARSING_ERROR – parsing data to config failed
133 · PMEMKV_STATUS_CONFIG_TYPE_ERROR – config item has different type than
135 expected
136
138 The following example is taken from examples/pmemkv_con‐
139 fig_c/pmemkv_config.c.
140 #include <assert.h>
142 #include <libpmemkv.h>
143 #include <libpmemkv_json_config.h>
144 #include <stdlib.h>
145 #include <string.h>
146 /* deleter for int pointer */
148 void free_int_ptr(void *ptr)
149 {
150 free(ptr);
151 }
152 int main()
154 {
155 pmemkv_config *config = pmemkv_config_new();
156 assert(config != NULL);
157 /* Put int64_t value */
159 int status = pmemkv_config_put_int64(config, "size", 1073741824);
160 assert(status == PMEMKV_STATUS_OK);
161 char buffer[] = "ABC";
163 /* Put binary data stored in buffer */
165 status = pmemkv_config_put_data(config, "binary", buffer, 3);
166 assert(status == PMEMKV_STATUS_OK);
167 const void *data;
169 size_t data_size;
170 /* Get pointer to binary data stored in config */
172 status = pmemkv_config_get_data(config, "binary", &data, &data_size);
173 assert(status == PMEMKV_STATUS_OK);
174 assert(data_size == 3);
175 assert(((const char *)data)[0] == 'A');
176 int *int_ptr = malloc(sizeof(int));
178 assert(int_ptr != NULL);
179 *int_ptr = 10;
180 /* Put pointer to dynamically allocated object, free_int_ptr is called on
182 * pmemkv_config_delete */
183 status = pmemkv_config_put_object(config, "int_ptr", int_ptr, &free_int_ptr);
184 assert(status == PMEMKV_STATUS_OK);
185 int *get_int_ptr;
187 /* Get pointer to object stored in config */
189 status = pmemkv_config_get_object(config, "int_ptr", (void **)&get_int_ptr);
190 assert(status == PMEMKV_STATUS_OK);
191 assert(*get_int_ptr == 10);
192 pmemkv_config_delete(config);
194 pmemkv_config *config_from_json = pmemkv_config_new();
196 assert(config_from_json != NULL);
197 /* Parse JSON and put all items found into config_from_json */
199 status = pmemkv_config_from_json(config_from_json, "{\"path\":\"/dev/shm\",\
200 \"size\":1073741824,\
201 \"subconfig\":{\
202 \"size\":1073741824\
203 }\
204 }");
205 assert(status == PMEMKV_STATUS_OK);
206 const char *path;
208 status = pmemkv_config_get_string(config_from_json, "path", &path);
209 assert(status == PMEMKV_STATUS_OK);
210 assert(strcmp(path, "/dev/shm") == 0);
211 pmemkv_config *subconfig;
213 /* Get pointer to nested configuration "subconfig" */
215 status = pmemkv_config_get_object(config_from_json, "subconfig",
216 (void **)&subconfig);
217 assert(status == PMEMKV_STATUS_OK);
218 size_t sub_size;
220 status = pmemkv_config_get_uint64(subconfig, "size", &sub_size);
221 assert(status == PMEMKV_STATUS_OK);
222 assert(sub_size == 1073741824);
223 pmemkv_config_delete(config_from_json);
225 return 0;
227 }
228
230 libpmemkv(7), libpmemkv(3) , libpmemkv_json_config(3) and
231 <https://pmem.io>
232PMEMKV - pmemkv version 1.1 2020-02-12 PMEMKV_CONFIG(3)