1Key :: Value Manipulation MeLtihbordasr(y3)FunctionKseyMa:n:uaVlalue Manipulation Methods(3)
2
3
4

NAME

6       Key :: Value Manipulation Methods - Methods to do various operations on
7       Key values.
8
9
10   Functions
11       ssize_t keyGetDataSize (const Key *key)
12           An alias to keyGetValueSize().
13       ssize_t keyGetValueSize (const Key *key)
14           Returns the number of bytes needed to store the key value,
15           including the NULL terminator.
16       ssize_t keySetString (Key *key, const char *newStringValue)
17           Set the value for key as newStringValue.
18       ssize_t keyGetString (const Key *key, char *returnedString, size_t
19           maxSize)
20           Get the value of a key as a string.
21       void * keyStealValue (const Key *key)
22           Return a pointer to the real internal key value.
23       ssize_t keySetLink (Key *key, const char *target)
24           Set key as type KeyType::KEY_TYPE_LINK with target target.
25       ssize_t keyGetLink (const Key *key, char *returnedTarget, size_t
26           maxSize)
27           Get the target key pointed by key.
28       ssize_t keyGetBinary (const Key *key, void *returnedValue, size_t
29           maxSize)
30           Get the binary or string value of key.
31       ssize_t keySetBinary (Key *key, const void *newBinary, size_t dataSize)
32           Set the value of a key as a binary.
33       uint8_t keyGetType (const Key *key)
34           Returns the key data type.
35       uint8_t keySetType (Key *key, uint8_t newType)
36           Force a key type.
37       uint8_t keySetDir (Key *key, mode_t customUmask)
38           Force a key type to be KEY_TYPE_DIR and set permissions.
39       ssize_t keySetRaw (Key *key, const void *newBinary, size_t dataSize)
40           Set raw data as the value of a key.
41

Detailed Description

43       Methods to do various operations on Key values.
44
45       A key can contain a value in different format. The most likely
46       situation is, that the value is interpreted as text. Use keyGetString()
47       for that. You can save any Unicode Symbols and Elektra will take care
48       that you get the same back, independent of your current environment.
49
50       In some situations this idea fails. When you need exactly the same
51       value back without any interpretation of the characters, there is
52       keySetBinary(). If you use that, its very likely that your
53       Configuration is not according to the standard. Also for Numbers,
54       Booleans and Date you should use keyGetString(). To do so, you might
55       use strtod() strtol() and then atol() or atof() to convert back.
56
57       A key may also be just a link. Here you will also find the manipulation
58       methods for keyGetLink().
59
60       To use them:
61
62       #include <kdb.h>
63
64

Function Documentation

66   ssize_t keyGetValueSize (const Key * key)
67       Returns the number of bytes needed to store the key value, including
68       the NULL terminator.
69
70       This method is used with malloc() before a keyGetString() or
71       keyGetBinary().
72
73       Returns:
74           the number of bytes needed to store the key value
75
76       See also:
77           keyGetString(), keyGetBinary(), keyStealValue()
78
79       Definition at line 1602 of file key.c.
80
81       References _Key::dataSize.
82
83       Referenced by commandGet(), keyGetDataSize(), and listSingleKey().
84
85   ssize_t keySetString (Key * key, const char * newStringValue)
86       Set the value for key as newStringValue.
87
88       The function will allocate and save a private copy of newStringValue,
89       so the parameter can be freed after the call.
90
91       String values will be saved in backend storage, when kdbSetKey() will
92       be called, in UTF-8 universal encoding,regardeless of the program's
93       current encoding.
94
95       Parameters:
96           key the key to set the string value
97           newStringValue NULL-terminated text string to be set as key's value
98
99       Returns:
100           the number of bytes actually saved in private struct including
101           final NULL
102
103       See also:
104           keyGetString(), keyStealValue()
105
106       Definition at line 1625 of file key.c.
107
108       References KEY_TYPE_STRING, keySetRaw(), keySetType(), and strblen().
109
110       Referenced by commandSet(), kdbSetValue(), and keyNew().
111
112   ssize_t keyGetString (const Key * key, char * returnedString, size_t
113       maxSize)
114       Get the value of a key as a string.
115
116       If the value can't be represented as a text string (binary value, see
117       keyIsBin()), errno is set to KDBErr::KDB_RET_TYPEMISMATCH.
118
119       Example:.RS 4
120
121
122       Key *key;
123       char buffer[300];
124
125       // populate key somehow...
126
127       if (keyIsBin(key)) keyGetBinary(key,buffer,sizeof(buffer));
128       else keyGetString(key,buffer,sizeof(buffer));
129
130
131       Parameters:
132           key the object to gather the value
133           returnedString pre-allocated memory to store a copy of the key
134           value
135           maxSize number of bytes of pre-allocated memory in returnedString
136
137       Returns:
138           the number of bytes actually copied to returnedString, including
139           final NULL
140
141       See also:
142           keyStealValue(), keySetString(), keyGetBinary()
143
144       Definition at line 1662 of file key.c.
145
146       References _Key::data, _Key::dataSize, KDB_RET_NODATA, KDB_RET_TRUNC,
147       KDB_RET_TYPEMISMATCH, KEY_TYPE_STRING, and _Key::type.
148
149       Referenced by commandGet(), kdbGetValue(), and listSingleKey().
150
151   void* keyStealValue (const Key * key)
152       Return a pointer to the real internal key value.
153
154       This is a much more efficient version of keyGetString(), keyGetLink(),
155       keyGetBinary(), and you should use it if you are responsible enough to
156       not mess up things.
157
158       If key is not binary (keyIsBin()), you may cast the returned as a 'char
159       *' because you'll get a NULL terminated regular string. If it is
160       binary, the size of the value can be determined by keyGetValueSize().
161
162       Note that the Key structure also has as data size field that is
163       calculated by library internal calls to keySetRaw(), so to avoid
164       inconsistencies, you must never used the pointer returned by
165       keyStealValue() method to set a new value. Use keySetString(),
166       keySetBinary(), keySetLink(), keySetRaw() instead.
167
168       Example:.RS 4
169
170
171       KeySet *ks=ksNew();
172       Key *current=0;
173
174       kdbGetChildKeys('system/sw/my',ks,KDB_O_SORT|KDB_O_RECURSIVE);
175
176       ksRewind(ks);
177       while(current=ksNext(ks)) {
178           size_t size=0;
179
180           if (keyIsBin(current)) {
181               size=keyGetValueSize(current);
182               printf('Key %s has a value of size %d bytes. Value: <BINARY>0omment: %s',
183                   keyStealName(current),
184                   size,
185                   keyStealComment(current));
186           } else {
187               size=strblen((char *)keyStealValue(current));
188               printf('Key %s has a value of size %d bytes. Value: %s0omment: %s',
189                   keyStealName(current),
190                   size,
191                   (char *)keyStealValue(current),
192                   keyStealComment(current));
193           }
194       }
195
196
197       Parameters:
198           key the key object to work with
199
200       See also:
201           keyGetValueSize(), keyGetString(), keyGetBinary(), keyGetLink()
202
203       Definition at line 1737 of file key.c.
204
205       References _Key::data.
206
207       Referenced by commandMonitor(), and listAllKeysForShell().
208
209   ssize_t keySetLink (Key * key, const char * target)
210       Set key as type KeyType::KEY_TYPE_LINK with target target.
211
212       Parameters:
213           key the object to work with
214           target the value to set to key
215
216       Returns:
217           whatever returned by keySetRaw()
218
219       Definition at line 1757 of file key.c.
220
221       References KEY_TYPE_LINK, keySetRaw(), keySetType(), and strblen().
222
223       Referenced by commandSet(), and kdbLink().
224
225   ssize_t keyGetLink (const Key * key, char * returnedTarget, size_t maxSize)
226       Get the target key pointed by key.
227
228       Parameters:
229           returnedTarget a pre-allocated buffer to store the target
230           maxSize the size in bytes of the returnedTarget buffer
231           key the link key
232
233       Deprecated
234           link system not perfect that way
235
236       Returns:
237           the size in bytes of the copied target string
238
239       TODO: Remove or:
240
241       · update Doc
242
243       · add keyGetLinkSize()
244
245       Definition at line 1781 of file key.c.
246
247       References _Key::data, _Key::dataSize, KDB_RET_NODATA, KDB_RET_TRUNC,
248       KDB_RET_TYPEMISMATCH, KEY_TYPE_LINK, and _Key::type.
249
250       Referenced by listSingleKey().
251
252   ssize_t keyGetBinary (const Key * key, void * returnedValue, size_t
253       maxSize)
254       Get the binary or string value of key.
255
256       Parameters:
257           returnedValue pre-allocated memory to store a copy of key's value
258           maxSize number of bytes of pre-allocated memory
259
260       Returns:
261           the number of bytes actually copied to returnedValue
262
263       See also:
264           keySetBinary(), keyGetString(), keyStealValue(), keyIsBin()
265
266       Definition at line 1873 of file key.c.
267
268       References _Key::data, _Key::dataSize, KDB_RET_NODATA, and
269       KDB_RET_TRUNC.
270
271       Referenced by commandGet().
272
273   ssize_t keySetBinary (Key * key, const void * newBinary, size_t dataSize)
274       Set the value of a key as a binary.
275
276       A private copy of newBinary will allocated and saved inside key, so the
277       parameter can be deallocated after the call.
278
279       The filesys backend, when used through a kdbSetKey(), will make the
280       value be encoded into a human readable hex-digit text format.
281
282       Consider using a string key instead.
283
284       Parameters:
285           key the object on which to set the value
286           newBinary value octet stream
287           dataSize number of bytes to copy from newBinary
288
289       Returns:
290           the number of bytes actually copied to internal struct storage
291
292       See also:
293           keyGetBinary(), keyIsBin(), keyGetString(), keyStealValue(),
294           keySetString()
295
296       Definition at line 1908 of file key.c.
297
298       References KEY_TYPE_BINARY, keySetRaw(), and keySetType().
299
300   uint8_t keyGetType (const Key * key)
301       Returns the key data type.
302
303       See also:
304           keySetType(), keyIsBin(), keyIsDir(), keyIsLink()
305
306           KeyType
307
308       Returns:
309           the key type
310
311       Definition at line 1942 of file key.c.
312
313       References _Key::type.
314
315       Referenced by commandGet(), commandSet(), and listSingleKey().
316
317   uint8_t keySetType (Key * key, uint8_t newType)
318       Force a key type.
319
320       See the KeyType documentation to understand the concepts behind Elektra
321       key's value types.
322
323       This method is usually not needed, unless you are working with more
324       semantic value types, or want to force a specific value type for a key.
325       It is not usually needed because the data type is automatically set
326       when setting the key value.
327
328       Example:.RS 4
329
330
331       #define KEY_TYPE_COLOR (KEY_TYPE_STRING+4)
332
333       Key *color1;
334       Key *color2;
335
336       // Set color1 key
337       color1=keyNew('user/sw/MyApp/colors/someColor',
338           KEY_SWITCH_TYPE,KEY_TYPE_COLOR,
339           KEY_SWITCH_VALUE,'#4B52CA',
340           KEY_SWITCH_COMMENT,'a custom color',
341           KEY_SWITCH_END);
342
343       // Set color2 key
344       color2=keyNew('system/sw/MyApp/colors/green',
345           KEY_SWITCH_TYPE,KEY_TYPE_COLOR,
346           KEY_SWITCH_VALUE,'green',
347           KEY_SWITCH_COMMENT,'the green color',
348           KEY_SWITCH_END);
349
350       // Start affairs with Key database
351       kdbOpen();
352
353       // Commit the keys
354       kdbSetKey(color1);
355       kdbSetKey(color2);
356
357       // Reset memory related to our structures to reuse them later
358       keyClose(color1);
359       keyClose(color2);
360
361       // Retrieve keys from the database
362       keySetName(color1,'user/sw/MyApp/colors/someColor');
363       kdbGetKey(color1);
364
365       keySetName(color2,'system/sw/MyApp/colors/green');
366       kdbGetKey(color2);
367
368       // End of the affairs with Key database by now
369       kdbClose();
370
371       // Get the key types, which should be our user-defined KEY_TYPE_COLOR
372       uint8_t tcolor1=keyGetType(color1);
373       uint8_t tcolor2=keyGetType(color2);
374
375       keyDel(color1);
376       keyDel(color2);
377
378
379       When using KeyType::KEY_TYPE_DIR, this method will not set access
380       permissions to the key. You'll have to set it manually after
381       keySetType(), calling keySetAccess() with appropriate permissions. Or
382       use the keySetDir().
383
384       See also:
385           keyGetType()
386
387           keySetDir()
388
389           KeyType
390
391       Returns:
392           the new type
393
394       Definition at line 2019 of file key.c.
395
396       References _Key::flags, KEY_SWITCH_NEEDSYNC, KEY_TYPE_DIR, keySetDir(),
397       and _Key::type.
398
399       Referenced by commandSet(), keyNew(), keySetBinary(), keySetLink(), and
400       keySetString().
401
402   uint8_t keySetDir (Key * key, mode_t customUmask)
403       Force a key type to be KEY_TYPE_DIR and set permissions.
404
405       This method is provided as a convenience to avoid separate calls of
406       keySetType() and keySetAccess() and the complexities of calculating
407       permissions from umask().
408
409       This method should be used this way:.RS 4
410
411
412       Key *key=keyNew(KEY_SWITCH_END);
413       mode_t mask=umask(0);
414
415       // restore backup
416       umask(mask);
417
418       // set directory permissions based on my umask
419       keySetDir(key,mask);
420
421
422       Parameters:
423           key the key to set type and permissions
424           customUmask the umask of current session
425
426       Returns:
427           always KEY_TYPE_DIR
428
429       See also:
430           keySetUAccess()
431
432           keySetType()
433
434       Definition at line 2063 of file key.c.
435
436       References _Key::access, _Key::flags, KEY_SWITCH_NEEDSYNC, and
437       KEY_TYPE_DIR.
438
439       Referenced by commandSet(), keyNew(), and keySetType().
440
441   ssize_t keySetRaw (Key * key, const void * newBinary, size_t dataSize)
442       Set raw data as the value of a key.
443
444       If NULL pointers are passed, key value is cleaned. This method will not
445       change or set the key type, and should not be used unless working with
446       user-defined value types.
447
448       Parameters:
449           newBinary array of bytes to set as the value
450           dataSize number bytes to use from newBinary, including the final
451           NULL
452
453       Returns:
454           The number of bytes actually set in internall buffer.
455
456       See also:
457           keySetType(), keySetString(), keySetBinary()
458
459       Definition at line 2088 of file key.c.
460
461       References _Key::data, _Key::dataSize, _Key::flags,
462       KEY_SWITCH_NEEDSYNC, and KEY_SWITCH_VALUE.
463
464       Referenced by commandSet(), keyDup(), keyNew(), keySetBinary(),
465       keySetLink(), and keySetString().
466
467
468
469Elektra Project                   25 Mar 20K0e7y :: Value Manipulation Methods(3)