1Key :: Name Manipulation MetLhiobdrsa(r3y)FunctionsKeMyan:u:alName Manipulation Methods(3)
2
3
4

NAME

6       Key :: Name Manipulation Methods - Methods to do various operations on
7       Key names.
8
9
10   Functions
11       char * keyNameGetOneLevel (const char *keyName, size_t *size)
12           Returns one level of the key name.
13       ssize_t keySetName (Key *key, const char *newName)
14           Set a new name to a key.
15       ssize_t keyAddBaseName (Key *key, const char *baseName)
16           Adds baseName to the current key name.
17       ssize_t keySetBaseName (Key *key, const char *baseName)
18           Sets baseName as the new basename for key.
19       ssize_t keyGetNameSize (const Key *key)
20           Bytes needed to store the key name without user domain.
21       ssize_t keyGetName (const Key *key, char *returnedName, size_t maxSize)
22           Get abreviated key name (without user domain name).
23       char * keyStealName (const Key *key)
24           Returns a pointer to the real internal key abreviated name (without
25           user domain name).
26       ssize_t keyGetFullNameSize (const Key *key)
27           Bytes needed to store the key name including user domain and ending
28           NULL.
29       ssize_t keyGetFullName (const Key *key, char *returnedName, size_t
30           maxSize)
31           Get key full name, including the user domain name.
32       int keyNameIsSystem (const char *keyName)
33           Check whether a key name is under the system namespace or not.
34       int keyNameIsUser (const char *keyName)
35           Check whether a key name is under the user namespace or not.
36       ssize_t keyNameGetFullRootNameSize (const char *keyName)
37           Gets number of bytes needed to store root name of a key name.
38       ssize_t keyGetRootNameSize (const Key *key)
39           Gets number of bytes needed to store root name of a key.
40       ssize_t keyGetRootName (const Key *key, char *returned, size_t maxSize)
41           Copy to returned the root name of key.
42       ssize_t keyNameGetRootNameSize (const char *keyName)
43           Gets number of bytes needed to store root name of a key name
44           without user domain.
45       ssize_t keyGetFullRootNameSize (const Key *key)
46           Calculates number of bytes needed to store full root name of a key.
47       ssize_t keyGetFullRootName (const Key *key, char *returned, size_t
48           maxSize)
49           Copy to returned the full root name of the key.
50       ssize_t keyGetParentNameSize (const Key *key)
51           Get the number of bytes needed to store this key's parent name
52           without user domain, and with the ending NULL.
53       ssize_t keyGetParentName (const Key *key, char *returnedParent, size_t
54           maxSize)
55           Copy this key's parent name (without user domain) into a pre-
56           allocated buffer.
57       ssize_t keyNameGetBaseNameSize (const char *keyName)
58           Calculates number of bytes needed to store a basename of a key name
59           including the ending NULL.
60       ssize_t keyGetBaseNameSize (const Key *key)
61           Calculates number of bytes needed to store basename of key.
62       ssize_t keyGetBaseName (const Key *key, char *returned, size_t maxSize)
63           Calculate the basename of a key name and put it in returned
64           finalizing the string with NULL.
65       char * keyStealBaseName (const Key *key)
66           Returns a pointer to the real internal key name where the basename
67           starts.
68

Detailed Description

70       Methods to do various operations on Key names.
71
72       To use them:
73
74       #include <kdb.h>
75
76
77       Rules for Key Names.RS 4
78
79
80When using Elektra to store your application's configuration and state, please
81keep in mind the following rules:
82
83· You are not allowed to create keys right under system or user.
84
85· You are not allowed to create folder keys right under system or user. They
86  are reserved for very essential OS subsystems.
87
88· The keys for your application, called say MyApp, should be created under
89  system/sw/MyApp and/or user/sw/MyApp.
90
91· It is suggested to make your application look for default keys under
92  system/sw/MyApp/current and/or user/sw/MyApp/current. This way, from a
93  sysadmin perspective, it will be possible to copy the
94  system/sw/MyApp/current tree to something like system/sw/MyApp/old, and keep
95  system clean and organized.
96

Function Documentation

98   char* keyNameGetOneLevel (const char * keyName, size_t * size)
99       Returns one level of the key name.
100
101       This method is used to skip repeating '/' and to find escaping chars.
102       Given keyName, this method returns a pointer to the next name level
103       found and changes size to the number of bytes on this level name.
104
105       This method is used by keySetName() and others to cleanup parameters
106       before being accepted in the Key object.
107
108       // Lets define a key name with a lot of repeating '/' and escaped '/'
109       char *keyName='user////abc/defghi////jkl///';
110       char *p;
111       size_t size=0;
112       int level=0;
113       char buffer[20];
114
115       p=keyName;
116       while (*(p=keyNameGetOneLevel(p+size,&size)!=0) {
117           level++;
118
119           // copy what we found to a buffer, so we can NULL-terminate it
120           strncpy(buffer,p,size);
121           buffer[size]=0;
122
123           printf('Level %d name: ´%s´0,level,buffer);
124       }
125
126       The above example will produce the following output:
127
128       Level 1 name: user
129       Level 2 name: abc
130       Level 3 name: defghi
131       Level 4 name: jkl
132
133       Parameters:
134           keyName the string that will be searched
135           size the number of bytes of level name found in keyName until the
136           next delimiter ('/')
137
138       Returns:
139           a pointer to the first char of the next level name
140
141       Definition at line 569 of file key.c.
142
143       Referenced by keyAddBaseName(), keyGetBaseName(),
144       keyGetParentNameSize(), keyNameGetBaseNameSize(), keySetBaseName(),
145       keySetName(), and keyStealBaseName().
146
147   ssize_t keySetName (Key * key, const char * newName)
148       Set a new name to a key.
149
150       A valid name is of the forms:
151
152       · system/something
153
154       · user/something
155
156       · user:username/something
157
158       The last form has explicitly set the user domain, to let the library
159       know in which user folder to save the key. A user domain is a user
160       name. If not defined (the second form) current user is calculated and
161       used as default.
162
163       You should always follow the guidelines for key tree structure creation
164       at Rules for Key Names.
165
166       A private copy of the key name will be stored, and the newName
167       parameter can be freed after this call.
168
169       Returns:
170           size in bytes of this new key name including ending NULL, or 0 if
171           newName is empty, or if newName is invalid, in which case errno is
172           set to KDBErrr::KDB_RET_INVALIDKEY.
173
174       Parameters:
175           key the key object
176           newName the new key name
177
178       See also:
179           keyNew(), keySetOwner()
180
181           keyGetName(), keyGetFullName(), keyStealName()
182
183       Definition at line 629 of file key.c.
184
185       References _Key::flags, KDB_RET_INVALIDKEY, KDB_RET_NOMEM, _Key::key,
186       KEY_SWITCH_DOMAIN, KEY_SWITCH_ISSYSTEM, KEY_SWITCH_ISUSER,
187       KEY_SWITCH_NAME, KEY_SWITCH_NEEDSYNC, keyNameGetFullRootNameSize(),
188       keyNameGetOneLevel(), keyNameIsSystem(), keyNameIsUser(),
189       keySetOwner(), strblen(), and _Key::userDomain.
190
191       Referenced by commandGet(), kdbGetKeyByParent(),
192       kdbGetKeyByParentKey(), kdbRemove(), kdbRename_default(),
193       keyAddBaseName(), keyDup(), keyNew(), keySetBaseName(), and
194       keyUnserialize().
195
196   ssize_t keyAddBaseName (Key * key, const char * baseName)
197       Adds baseName to the current key name.
198
199       Assumes that key is a directory. baseName is appended to it. The
200       function adds '/' if needed while concatenating.
201
202       So if key has name 'system/dir1/dir2' and this method is called with
203       baseName 'mykey', the resulting key will have name
204       'system/dir1/dir2/mykey'.
205
206       Returns:
207           the size in bytes of the new key name including the ending NULL
208
209       See also:
210           keySetBaseName()
211
212       Definition at line 786 of file key.c.
213
214       References KDB_RET_NOMEM, _Key::key, keyNameGetOneLevel(),
215       keySetName(), and strblen().
216
217   ssize_t keySetBaseName (Key * key, const char * baseName)
218       Sets baseName as the new basename for key.
219
220       All text after the last '/' in the key keyname is erased and baseName
221       is appended.
222
223       So lets suppose key has name 'system/dir1/dir2/key1'. If baseName is
224       'key2', the resulting key name will be 'system/dir1/dir2/key2'. If
225       baseName is empty or NULL, the resulting key name will be
226       'system/dir1/dir2'.
227
228       Returns:
229           the size in bytes of the new key name or -1 on error, and errno is
230           set to KDBErr::KDB_RET_NOMEM
231
232       See also:
233           keyAddBaseName()
234
235       Definition at line 849 of file key.c.
236
237       References KDB_RET_NOMEM, _Key::key, keyNameGetOneLevel(),
238       keySetName(), and strblen().
239
240   ssize_t keyGetNameSize (const Key * key)
241       Bytes needed to store the key name without user domain.
242
243       Returns:
244           number of bytes needed, including ending NULL, to store key name
245           without user domain
246
247       See also:
248           keyGetName(), keyGetFullNameSize()
249
250       Definition at line 920 of file key.c.
251
252       References _Key::key, and strblen().
253
254       Referenced by commandGet(), commandMove(), kdbMonitorKey_default(),
255       ksGetCommonParentName(), and ksLookupRE().
256
257   ssize_t keyGetName (const Key * key, char * returnedName, size_t maxSize)
258       Get abreviated key name (without user domain name).
259
260       Returns:
261           number of bytes written to returnedName
262
263       Parameters:
264           key the key object
265           returnedName pre-allocated memory to write the key name
266           maxSize maximum number of bytes that will fit in returnedName,
267           including the final NULL
268
269       See also:
270           keyGetNameSize(), keyGetFullName(), keyGetFullNameSize()
271
272       Definition at line 938 of file key.c.
273
274       References KDB_RET_NOKEY, KDB_RET_TRUNC, _Key::key, and strblen().
275
276       Referenced by commandGet(), and listSingleKey().
277
278   char* keyStealName (const Key * key)
279       Returns a pointer to the real internal key abreviated name (without
280       user domain name).
281
282       This is a much more efficient version of keyGetName() and you should
283       use it if you are responsible enough to not mess up things.
284
285       Parameters:
286           key the key object
287
288       See also:
289           keyGetNameSize(), keyGetFullName(), keyGetFullNameSize()
290
291           keyStealValue() for an example
292
293       Definition at line 968 of file key.c.
294
295       References _Key::key.
296
297       Referenced by ksLookupByName(), and listAllKeysForShell().
298
299   ssize_t keyGetFullNameSize (const Key * key)
300       Bytes needed to store the key name including user domain and ending
301       NULL.
302
303       Returns:
304           number of bytes needed to store key name including user domain
305
306       See also:
307           keyGetFullName(), keyGetNameSize()
308
309       Definition at line 984 of file key.c.
310
311       References _Key::key, keyNameIsUser(), strblen(), and _Key::userDomain.
312
313       Referenced by commandGet(), kdbGetKeyByParentKey(), keyGetFullName(),
314       and keySerialize().
315
316   ssize_t keyGetFullName (const Key * key, char * returnedName, size_t
317       maxSize)
318       Get key full name, including the user domain name.
319
320       Returns:
321           number of bytes written
322
323       Parameters:
324           key the key object
325           returnedName pre-allocated memory to write the key name
326           maxSize maximum number of bytes that will fit in returnedName,
327           including the final NULL
328
329       Definition at line 1015 of file key.c.
330
331       References KDB_RET_NOKEY, KDB_RET_TRUNC, _Key::key,
332       keyGetFullNameSize(), keyIsUser(), strblen(), and _Key::userDomain.
333
334       Referenced by commandEdit(), commandGet(), commandImport(),
335       kdbGetKeyByParentKey(), keySerialize(), keyToStreamBasename(), and
336       listSingleKey().
337
338   int keyNameIsSystem (const char * keyName)
339       Check whether a key name is under the system namespace or not.
340
341       Returns:
342           1 if string begins with system , 0 otherwise
343
344       Parameters:
345           keyName the name of a key
346
347       See also:
348           keyIsSystem(), keyIsUser(), keyNameIsUser()
349
350       Definition at line 1099 of file key.c.
351
352       Referenced by keyNameGetNamespace(), keyNameGetRootNameSize(), and
353       keySetName().
354
355   int keyNameIsUser (const char * keyName)
356       Check whether a key name is under the user namespace or not.
357
358       Returns:
359           1 if string begins with user, 0 otherwise
360
361       Parameters:
362           keyName the name of a key
363
364       See also:
365           keyIsSystem(), keyIsUser(), keyNameIsSystem()
366
367       Definition at line 1129 of file key.c.
368
369       Referenced by keyGetFullNameSize(), keyNameGetNamespace(),
370       keyNameGetRootNameSize(), and keySetName().
371
372   ssize_t keyNameGetFullRootNameSize (const char * keyName)
373       Gets number of bytes needed to store root name of a key name.
374
375       Possible root key names are system, user or 'user:someuser' .
376
377       Returns:
378           number of bytes needed with ending NULL
379
380       Parameters:
381           keyName the name of the key
382
383       See also:
384           keyGetFullRootNameSize()
385
386       Definition at line 1160 of file key.c.
387
388       Referenced by keySetName().
389
390   ssize_t keyGetRootNameSize (const Key * key)
391       Gets number of bytes needed to store root name of a key.
392
393       Possible root key names are system or user . This method does not
394       consider the user domain in user:username keys.
395
396       Returns:
397           number of bytes needed with the ending NULL
398
399       See also:
400           keyGetFullRootNameSize(), keyNameGetRootNameSize()
401
402       Definition at line 1195 of file key.c.
403
404       References _Key::key, and keyIsUser().
405
406       Referenced by keyGetFullRootName(), and keyGetRootName().
407
408   ssize_t keyGetRootName (const Key * key, char * returned, size_t maxSize)
409       Copy to returned the root name of key.
410
411       Some examples:
412
413       · root of system/some/key is system
414
415       · root of user:denise/some/key is user
416
417       · root of user/env/env1 is user
418
419       Use keyGetFullRootName() to get also the user domain.
420
421       Parameters:
422           key the key to extract root from
423           returned a pre-allocated buffer to store the rootname
424           maxSize size of the returned buffer
425
426       Returns:
427           number of bytes needed with ending NULL
428
429       See also:
430           keyNameGetRootNameSize(), keyGetRootNameSize(),
431           keyGetFullRootName()
432
433       Definition at line 1221 of file key.c.
434
435       References KDB_RET_NOKEY, KDB_RET_TRUNC, _Key::key, and
436       keyGetRootNameSize().
437
438   ssize_t keyNameGetRootNameSize (const char * keyName)
439       Gets number of bytes needed to store root name of a key name without
440       user domain.
441
442       Some examples:
443
444       · root of system/some/key is system
445
446       · root of user:denise/some/key is user
447
448       · root of user/env/env1 is user
449
450       Parameters:
451           keyName the name of the key
452
453       Returns:
454           number of bytes needed with ending NULL or -1 if keyName is not a
455           valid name and errno is set to KDBErr::KDB_RET_INVALIDKEY
456
457       See also:
458           keyGetRootNameSize()
459
460       Definition at line 1262 of file key.c.
461
462       References KDB_RET_INVALIDKEY, keyNameIsSystem(), and keyNameIsUser().
463
464       Referenced by keyGetFullRootNameSize().
465
466   ssize_t keyGetFullRootNameSize (const Key * key)
467       Calculates number of bytes needed to store full root name of a key.
468
469       Possible root key names are system, user or user:someuser. In contrast
470       to keyGetRootNameSize(), this method considers the user domain part,
471       and you should prefer this one.
472
473       Returns:
474           number of bytes needed with ending NULL
475
476       See also:
477           keyNameGetRootNameSize(), keyGetRootNameSize()
478
479       Definition at line 1304 of file key.c.
480
481       References _Key::key, keyIsUser(), keyNameGetRootNameSize(), strblen(),
482       and _Key::userDomain.
483
484       Referenced by keyGetFullRootName().
485
486   ssize_t keyGetFullRootName (const Key * key, char * returned, size_t
487       maxSize)
488       Copy to returned the full root name of the key.
489
490       Some examples:
491
492       · root of system/some/key is system
493
494       · root of user:denise/some/key is user:denise
495
496       · root of user/env/env1 is user:$USER
497
498       This method is more robust then keyGetRootName()
499
500       Parameters:
501           key the key to extract root from
502           returned a pre-allocated buffer to store the rootname
503           maxSize size of the returned buffer
504
505       Returns:
506           number of bytes written to returned including ending NULL
507
508       See also:
509           keyGetFullRootNameSize(), keyGetRootName()
510
511       Definition at line 1335 of file key.c.
512
513       References KDB_RET_NOKEY, KDB_RET_TRUNC, _Key::key,
514       keyGetFullRootNameSize(), keyGetRootNameSize(), keyIsUser(), and
515       _Key::userDomain.
516
517   ssize_t keyGetParentNameSize (const Key * key)
518       Get the number of bytes needed to store this key's parent name without
519       user domain, and with the ending NULL.
520
521       See also:
522           keyGetParentName() for example
523
524       Definition at line 1383 of file key.c.
525
526       References KDB_RET_NOKEY, _Key::key, and keyNameGetOneLevel().
527
528       Referenced by keyGetParentName(), and ksLookupRE().
529
530   ssize_t keyGetParentName (const Key * key, char * returnedParent, size_t
531       maxSize)
532       Copy this key's parent name (without user domain) into a pre-allocated
533       buffer.
534
535       See also:
536           keyGetParentNameSize()
537
538       Parameters:
539           returnedParent pre-allocated buffer to copy parent name to
540           maxSize number of bytes pre-allocated
541
542       Returns:
543           number of bytes copied including ending NULL
544
545       Example:.RS 4
546
547
548       Key *key=keyNew('system/parent/base',KEY_SWITCH_END);
549       char *parentName;
550       size_t parentSize;
551
552       parentSize=keyGetParentNameSize(key);
553       parentName=malloc(parentSize);
554       keyGetParentName(key,parentName,parentSize);
555
556
557       Definition at line 1439 of file key.c.
558
559       References KDB_RET_TRUNC, _Key::key, and keyGetParentNameSize().
560
561       Referenced by ksLookupRE().
562
563   ssize_t keyNameGetBaseNameSize (const char * keyName)
564       Calculates number of bytes needed to store a basename of a key name
565       including the ending NULL.
566
567       Key names that have only root names (e.g. 'system' or 'user' or
568       'user:domain' ) does not have basenames, thus the function will return
569       0 bytes.
570
571       Basenames are denoted as:
572
573       · system/some/thing/basename -> basename
574
575       · user:domain/some/thing/base\/name -> base\/name
576
577       Returns:
578           size in bytes of basename including ending NULL
579
580       See also:
581           keyGetBaseNameSize()
582
583       Definition at line 1475 of file key.c.
584
585       References keyNameGetOneLevel().
586
587       Referenced by keyGetBaseNameSize().
588
589   ssize_t keyGetBaseNameSize (const Key * key)
590       Calculates number of bytes needed to store basename of key.
591
592       Key names that have only root names (e.g. 'system' or 'user' or
593       'user:domain' ) does not have basenames, thus the function will return
594       0 bytes.
595
596       Basenames are denoted as:
597
598       · system/some/thing/basename -> basename
599
600       · user:domain/some/thing/base\/name > base\/name
601
602       Returns:
603           size in bytes of key's basename including ending NULL
604
605       See also:
606           keyNameGetBaseNameSize()
607
608       Definition at line 1506 of file key.c.
609
610       References _Key::key, and keyNameGetBaseNameSize().
611
612       Referenced by commandGet().
613
614   ssize_t keyGetBaseName (const Key * key, char * returned, size_t maxSize)
615       Calculate the basename of a key name and put it in returned finalizing
616       the string with NULL.
617
618       Some examples:
619
620       · basename of system/some/keyname is keyname
621
622       · basename of 'user/tmp/some key' is 'some key'
623
624       Parameters:
625           key the key to extract basename from
626           returned a pre-allocated buffer to store the basename
627           maxSize size of the returned buffer
628
629       Returns:
630           number of bytes copied to returned, or 0 and errno is set
631
632       See also:
633           keyStealBaseName(), keyGetBaseNameSize()
634
635       Definition at line 1529 of file key.c.
636
637       References KDB_RET_TRUNC, _Key::key, and keyNameGetOneLevel().
638
639       Referenced by commandGet().
640
641   char* keyStealBaseName (const Key * key)
642       Returns a pointer to the real internal key name where the basename
643       starts.
644
645       This is a much more efficient version of keyGetBaseName() and you
646       should use it if you are responsible enough to not mess up things.
647
648       Parameters:
649           key the object to obtain the basename from
650
651       See also:
652           keyGetBaseName(), keyGetBaseNameSize()
653
654       Definition at line 1562 of file key.c.
655
656       References _Key::key, and keyNameGetOneLevel().
657
658
659
660Elektra Project                   25 Mar 200K7ey :: Name Manipulation Methods(3)