1KeySet :: Class Methods(3) Library Functions Manual KeySet :: Class Methods(3)
2
6 KeySet :: Class Methods - Methods to manipulate KeySets.
7 Functions
10 KeySet * ksNew ()
11 Allocate, initialize and return a new KeySet object.
12 int ksDel (KeySet *ks)
13 A destructor for KeySet objects.
14 ssize_t ksGetSize (KeySet *ks)
15 Return the number of keys that ks contains.
16 int ksRewind (KeySet *ks)
17 Resets a KeySet internal cursor.
18 Key * ksNext (KeySet *ks)
19 Returns the next Key in a KeySet.
20 Key * ksCurrent (const KeySet *ks)
21 Return the current Key.
22 Key * ksHead (KeySet *ks)
23 Return the first key in the KeySet, without changing the KeySet's
24 internal cursor.
25 Key * ksTail (KeySet *ks)
26 Return the last key in the KeySet, without changing the KeySet's
27 internal cursor.
28 Key * ksLookupByName (KeySet *ks, const char *name, unsigned long
29 options)
30 Look for a Key contained in ks that matches name, starting from ks'
31 ksNext() position.
32 uint32_t ksLookupRE (KeySet *ks, uint32_t where, const regex_t *regexp,
33 unsigned long options)
34 Lookup for a key which any of its where components matches the
35 regex regular expression.
36 Key * ksLookupByValue (KeySet *ks, const char *value, unsigned long
37 options)
38 Lookup for a Key contained in ks KeySet that matches value,
39 starting from ks' ksNext() position.
40 Key * ksLookupByBinaryValue (KeySet *ks, void *value, size_t size,
41 unsigned long options)
42 Lookup for a Key contained in ks KeySet that matches the binary
43 value, starting from ks' ksNext() position.
44 ssize_t ksInsert (KeySet *ks, Key *toInsert)
45 Insert a new Key in the beginning of the KeySet.
46 Key * ksPop (KeySet *ks)
47 Remove and return the first key of ks.
48 Key * ksPopLast (KeySet *ks)
49 Remove and return the last key of ks.
50 ssize_t ksInsertKeys (KeySet *ks, KeySet *toInsert)
51 Transfers all keys from toInsert to the begining of ks.
52 ssize_t ksAppend (KeySet *ks, Key *toAppend)
53 Appends a new Key to the end of ks.
54 ssize_t ksAppendKeys (KeySet *ks, KeySet *toAppend)
55 Transfers all toAppend contained keys to the end of the ks.
56 int ksCompare (KeySet *ks1, KeySet *ks2, KeySet *removed)
57 Compare 2 KeySets.
58 ssize_t ksToStream (const KeySet *ks, FILE *stream, unsigned long
59 options)
60 Writes to stream an XML version of the ks object.
61 ssize_t ksGetCommonParentName (const KeySet *ks, char
62 *returnedCommonParent, const size_t maxSize)
63 Calculates the common parent to all keys in ks.
64 void ksSort (KeySet *ks)
65 Sorts a KeySet aphabetically by Key name, using qsort().
66 int ksInit (KeySet *ks)
67 KeySet object initializer.
68 int ksClose (KeySet *ks)
69 KeySet object cleaner.
70
72 Methods to manipulate KeySets.
73 A KeySet is a linked list to group a number of Keys. KeySets have an
75 internal cursor to help in the Key navigation.
76 These are the methods to make various manipulations in the objects of
78 class KeySet. Methods for sorting , merging , comparing , and internal
79 cursor manipulation are provided.
80 KeySet has a fundamental meaning inside elektra. It makes it possible
82 to get and store many keys at once inside the database. In addition to
83 that the class can be used as high level datastructure in applications.
84 With ksLookupByName it is possible to fetch easily specific keys out of
85 the list of keys.
86 To use them:
88 #include <kdb.h>
90
93 KeySet* ksNew ()
94 Allocate, initialize and return a new KeySet object.
95 Objects created with ksNew() must be destroyed with ksDel().
97 Use this function if you want to create a new KeySet.
99 Due to ABI compatibility, the KeySet structure is only declared in
101 kdb.h, and not defined. So you can only declare pointers to KeySets in
102 your program.
103 See http://tldp.org/HOWTO/Program-Library-HOWTO/shared-
105 libraries.html#AEN135
106 See also:
108 ksDel()
109 Returns:
111 a ready to use KeySet object
112 Definition at line 93 of file keyset.c.
114 References ksInit().
116 Referenced by commandEdit(), commandImport(), and commandList().
118 int ksDel (KeySet * ks)
120 A destructor for KeySet objects.
121 Cleans all internal dynamic attributes, keyDel() all contained Keys,
123 and free()s the release the KeySet object memory (that was previously
124 allocated by ksNew()).
125 See also:
127 ksNew(), ksClose()
128 Returns:
130 always 0
131 Definition at line 111 of file keyset.c.
133 References ksClose().
135 Referenced by commandEdit(), commandImport(), and commandList().
137 ssize_t ksGetSize (KeySet * ks)
139 Return the number of keys that ks contains.
140 Returns:
142 the number of keys that ks contains.
143 See also:
145 ksNew(), ksDel()
146 Definition at line 127 of file keyset.c.
148 References _KeySet::size.
150 Referenced by commandEdit(), and listAllKeys().
152 int ksRewind (KeySet * ks)
154 Resets a KeySet internal cursor.
155 Use it to set the cursor to the beginning of the KeySet. ksCurrent()
157 will then always return NULL afterwards. So you want to ksNext() first.
158 ksRewind (ks);
160 while (key = keyNext (ks)) {}
161 Returns:
163 always 0
164 See also:
166 ksNext(), kdbMonitorKeys() for an example
167 Definition at line 155 of file keyset.c.
169 References _KeySet::cursor.
171 Referenced by commandEdit(), commandImport(), ksLookupByName(),
173 ksLookupRE(), listAllKeys(), and listAllKeysForShell().
174 Key* ksNext (KeySet * ks)
176 Returns the next Key in a KeySet.
177 KeySets have an internal cursor that can be reset with ksRewind().
179 Every time ksNext() is called the cursor is incremented and the new
180 current Key is returned.
181 You'll get a NULL pointer if the end of KeySet was reached. After that,
183 if ksNext() is called again, it will set the cursor to the beginning of
184 the KeySet and the first key is returned.
185 Returns:
187 the new current Key
188 See also:
190 ksRewind(), ksCurrent()
191 Definition at line 177 of file keyset.c.
193 References _KeySet::cursor, _Key::next, and _KeySet::start.
195 Referenced by commandEdit(), commandImport(), kdbMonitorKeys_default(),
197 kdbSetKeys_default(), ksLookupByBinaryValue(), ksLookupByName(),
198 ksLookupByValue(), ksLookupRE(), listAllKeys(), and
199 listAllKeysForShell().
200 Key* ksCurrent (const KeySet * ks)
202 Return the current Key.
203 The pointer is NULL if you reached the end or after ksRewind().
205 Returns:
207 pointer to the Key pointed by ks's cursor
208 See also:
210 ksNext(), ksRewind()
211 kdbMonitorKeys() for a usage example
213 Definition at line 196 of file keyset.c.
215 References _KeySet::cursor.
217 Referenced by commandEdit(), commandImport(), kdbMonitorKeys_default(),
219 and kdbSetKeys_default().
220 Key* ksHead (KeySet * ks)
222 Return the first key in the KeySet, without changing the KeySet's
223 internal cursor.
224 See also:
226 ksTail(), ksCurrent(), ksNext()
227 ksRewind() which also resets the internal cursor.
229 Definition at line 209 of file keyset.c.
231 References _KeySet::start.
233 Referenced by listAllKeys().
235 Key* ksTail (KeySet * ks)
237 Return the last key in the KeySet, without changing the KeySet's
238 internal cursor.
239 See also:
241 ksHead(), ksCurrent(), ksNext()
242 Definition at line 221 of file keyset.c.
244 References _KeySet::end.
246 Key* ksLookupByName (KeySet * ks, const char * name, unsigned long options)
248 Look for a Key contained in ks that matches name, starting from ks'
249 ksNext() position.
250 The ksLookup*() set of methods are designed to let you work with
252 entirely pre-loaded KeySets, so instead of kdbGetKey(), key by key, the
253 idea is to fully kdbGetChildKeys() for your application root key (which
254 is more performatic), and process it all at once with ksLookup*().
255 The lookup process stops if the end of ks is reached. The idea behind
257 it is that your keyset processing logic consider a sorted KeySet and
258 process it in a alphabetical order. So your logic should first lookup
259 key aaa, then bbb, then ccc. This way you avoid going back to a
260 position in an already processed point.
261 This behavior changes if KDB_O_ALL option is used: all the KeySet is
263 searched, and if not found, it will stop with the current key.
264 If found, ks internal cursor will be positioned in the matched key
266 (also accessible by ksCurrent()), and a pointer to the Key is returned.
267 If not found, ks internal cursor will not move, and a NULL pointer is
268 returned.
269 Cascading is done if the first character is a /. This leads to ignoring
271 the prefix like system/ and user/.
272 if (kdbGetChildKeys('user/myapp', myConfig, 0 ) == -1)
274 BailOut ('Could not get Keys');
275 if (kdbGetChildKeys('system/myapp', myConfig, 0 ) == -1)
277 BailOut ('Could not get Keys');
278 if ((myKey = ksLookupByName (myConfig, '/myapp/key', 0)) == NULL)
280 BailOut ('Could not Lookup Key');
281 This is the way multi user Programs should get there configuration and
284 search after the values. It is guaranteed that more namespaces can be
285 added easily and that all values can be set by admin and user.
286 Parameters:
288 ks where to look for
289 name key name you are looking for
290 options some KDB_O_* option bits. Currently suported:
291 · KDB_O_NOCASE
293 Lookup ignoring case.
294 · KDB_O_ALL
296 Do not be satisfied if reached the end of keyset without finding
297 a a key that matches, and start over from the begining until
298 ksCurrent()
299 Returns:
301 pointer to the Key found, 0 otherwise
302 See also:
304 ksLookupRE() for powerfull regular expressions based lookups
305 keyCompare() for very powerfull Key lookups in KeySets
307 ksCurrent(), ksRewind(), ksNext()
309 Definition at line 294 of file keyset.c.
311 References _KeySet::cursor, KDB_O_ALL, KDB_O_NOCASE, _Key::key,
313 keyStealName(), ksNext(), ksRewind(), _KeySet::start, and strblen().
314 uint32_t ksLookupRE (KeySet * ks, uint32_t where, const regex_t * regexp,
316 unsigned long options)
317 Lookup for a key which any of its where components matches the regex
318 regular expression.
319 Parameters:
321 ks the KeySet to lookup into
322 where any of KEY_SWITCH_NAME, KEY_SWITCH_VALUE, KEY_SWITCH_OWNER,
323 KEY_SWITCH_COMMENT ORed.
324 regexp a regcomp(3) pre-compiled regular expression
325 options some KDB_O_* ORed options to change lookup behavior.
326 Currently supported options:
327 · KDB_O_NOSPANPARENT
329 Lookup only keys under ksCurrent()'s parent. If we are in the
330 begining of the KeySet (ksCurrent()==NULL), this option is
331 ignored. ks must be ksSort()ed (or kdbGetChildKeys() with
332 KDB_O_SORT ) for this to work.
333 · KDB_O_ALL
335 Do not be satisfied if reached the end of keyset without finding
336 a a key that matches, and start over from the begining until
337 ksCurrent()
338 Returns:
340 some of KEY_SWITCH_NAME, KEY_SWITCH_VALUE, KEY_SWITCH_OWNER,
341 KEY_SWITCH_COMMENT switches ORed to indicate where the regex
342 matched.
343 See also:
345 ksLookupByName(), ksLookupByValue(), keyCompare() for other types
346 of lookups.
347 kdbGetChildKeys(), ksSort()
349 Example:.RS 4
351 // This code will process all Devices options, device by device.
354 // Look how we use nested loops, palying with KDB_O_NOSPANPARENT.
355 // We can do more interesting things when playing with 2 or more regular
356 // expressions.
357 regex_t regex;
359 // you are NOT seeing spaces in this regex
361 regcomp(®ex,'.* /InputDevices/.* /Options/.*',REG_NOSUB);
362 where=KEY_SWITCH_NAME; // look for it only in key names
363 ksRewind(ks);
365 do {
366 // show all keys that match this name, and are siblings of the first match
367 match=ksLookupRE(ks,where,®ex,0);
368 if (match) {
369 // We found a device and its first option,
370 processOption(ksCurrent(ks));
372 // now process other options of this same device
374 do {
375 // fetch only the options with same parent with the
376 // help of KDB_O_NOSPANPARENT
377 match=ksLookupRE(ks,where,®ex,KDB_O_NOSPANPARENT);
378 if (match) processOption(ksCurrent(ks));
380 } while (match);
381 }
382 } while (match);
383 regfree(®ex); // free regex resources
385 Examples of regular expressions:.RS 4
388 regex_t regex;
391 // The spaces between '*' and '/' and '*' chars are Doxygen mirages :)
393 regcomp(®ex,
395 'some value .* more text', // match this
396 REG_NEWLINE | REG_NOSUB); // all in a single line
397 regcomp(®ex,
399 'Device/.* /Options/ *', // only interested in option keys
400 REG_ICASE | REG_NOSUB); // ignore case
401 regcomp(®ex,
403 '^system/folder/.* /basename$', // match real system/ keys that end with 'basename'
404 REG_NOSUB); // allways use REG_NOSUB to increase performance
405 regcomp(®ex,
407 '^system/sw/xorg/.* /Screen[0-9]* /Displays/[0-9]* /Depth$', // we want all X.org's depths of all displays of all screens
408 REG_ICASE | REG_NOSUB); // we don't care about the case
409 regfree(®ex); // don't forget to free resources
412 Definition at line 438 of file keyset.c.
415 References _Key::comment, _KeySet::cursor, _Key::data, KDB_O_ALL,
417 KDB_O_NOSPANPARENT, _Key::key, KEY_SWITCH_COMMENT, KEY_SWITCH_NAME,
418 KEY_SWITCH_OWNER, KEY_SWITCH_VALUE, KEY_TYPE_STRING, keyGetNameSize(),
419 keyGetParentName(), keyGetParentNameSize(), keyIsUser(), ksNext(),
420 ksRewind(), _KeySet::start, _Key::type, and _Key::userDomain.
421 Key* ksLookupByValue (KeySet * ks, const char * value, unsigned long
423 options)
424 Lookup for a Key contained in ks KeySet that matches value, starting
425 from ks' ksNext() position.
426 If found, ks internal cursor will be positioned in the matched key
428 (also accessible by ksCurrent()), and a pointer to the Key is returned.
429 If not found, ks internal cursor won't move, and a NULL pointer is
430 returned.
431 This method jumps binary keys, unless value is NULL.
433 Example:.RS 4
435 ksRewind(ks);
438 while (key=ksLookupByValue(ks,'my value',0)) {
439 // show all keys which value='my value'
440 keyToStream(key,stdout,0);
441 }
442 Parameters:
445 ks where to look for
446 value the value which owner key you want to find
447 options some KDB_O_* option bits. Currently supported:
448 · KDB_O_NOCASE
450 Lookup ignoring case.
451 Returns:
453 the Key found, 0 otherwise
454 See also:
456 ksLookupByBinaryValue()
457 keyCompare() for very powerfull Key lookups in KeySets
459 ksCurrent(), ksRewind(), ksNext()
461 TODO: Use macro instead
463 Definition at line 546 of file keyset.c.
465 References _KeySet::cursor, _Key::data, _Key::dataSize, KDB_O_NOCASE,
467 KEY_TYPE_STRING, ksNext(), strblen(), and _Key::type.
468 Key* ksLookupByBinaryValue (KeySet * ks, void * value, size_t size,
470 unsigned long options)
471 Lookup for a Key contained in ks KeySet that matches the binary value,
472 starting from ks' ksNext() position.
473 If found, ks internal cursor will be positioned in the matched key.
475 That means it is also accessible by ksCurrent(). A pointer to the Key
476 is returned. If not found, ks internal cursor won't move, and a NULL
477 pointer is returned.
478 Parameters:
480 ks where to look for
481 value the value which owner key you want to find
482 size the size of value
483 options some KDB_O_* option bits, for future use
484 Returns:
486 the Key found, NULL otherwise
487 See also:
489 ksLookupByValue()
490 keyCompare() for very powerfull Key lookups in KeySets
492 ksCurrent(), ksRewind(), ksNext()
494 TODO: use macro to check if dir!
496 Definition at line 596 of file keyset.c.
498 References _KeySet::cursor, _Key::data, _Key::dataSize, and ksNext().
500 ssize_t ksInsert (KeySet * ks, Key * toInsert)
502 Insert a new Key in the beginning of the KeySet.
503 A reference to the key will be stored, and not a copy of the key. So a
505 future ksClose() or ksDel() on ks will keyDel() the toInsert object.
506 The KeySet internal cursor is not moved.
508 Do not ksInsert() Keys that are already members of other KeySets.
510 Returns:
512 the size of the KeySet after insertion
513 Parameters:
515 ks KeySet that will receive the key
516 toInsert Key that will be inserted into ks
517 See also:
519 ksAppend(), ksInsertKeys(), ksAppendKeys(), ksDel(), keyNew()
520 Definition at line 645 of file keyset.c.
522 References _KeySet::end, _Key::next, _KeySet::size, and _KeySet::start.
524 Referenced by kdbGetRootKeys().
526 Key* ksPop (KeySet * ks)
528 Remove and return the first key of ks.
529 If ks' cursor was positioned in the poped key, ks will be ksRewind()ed.
531 ksInsert() provides the 'push' bahavior.
533 Returns:
535 the first key of ks, or NULL if ks is empty
536 Parameters:
538 ks KeySet to work with
539 See also:
541 ksInsert(), ksRewind()
542 commandList() for an example
544 Definition at line 665 of file keyset.c.
546 References _KeySet::cursor, _KeySet::end, _Key::next, _KeySet::size,
548 and _KeySet::start.
549 Referenced by commandList().
551 Key* ksPopLast (KeySet * ks)
553 Remove and return the last key of ks.
554 If ks' cursor was positioned in the poped key, ks will be ksRewind()ed.
556 ksAppend() provides the 'push' bahavior.
558 Returns:
560 the last key of ks, or NULL if ks is empty
561 Parameters:
563 ks KeySet to work with
564 See also:
566 ksAppend(), ksRewind()
567 commandList() and ksCompare() for examples
569 Definition at line 692 of file keyset.c.
571 References _KeySet::cursor, _KeySet::end, _Key::next, _KeySet::size,
573 and _KeySet::start.
574 ssize_t ksInsertKeys (KeySet * ks, KeySet * toInsert)
576 Transfers all keys from toInsert to the begining of ks.
577 After this call, toInsert will be empty and can be deleted with
579 ksDel().
580 Returns:
582 the size of the KeySet after insertion
583 Parameters:
585 ks the KeySet that will receive the keys
586 toInsert the KeySet that provides the keys that will be transfered
587 See also:
589 ksAppend(), ksInsert(), ksAppendKeys()
590 Definition at line 732 of file keyset.c.
592 References _KeySet::cursor, _KeySet::end, _Key::next, _KeySet::size,
594 and _KeySet::start.
595 ssize_t ksAppend (KeySet * ks, Key * toAppend)
597 Appends a new Key to the end of ks.
598 A reference to the key will be stored, and not a private copy. So a
600 future ksClose() or ksDel() on ks will keyDel() the toAppend object.
601 The KeySet internal cursor is not moved.
602 Do not ksAppend() Keys that are already contained by other KeySets.
604 Returns:
606 the size of the KeySet after insertion
607 Parameters:
609 ks KeySet that will receive the key
610 toAppend Key that will be appended to ks
611 See also:
613 ksInsert(), ksInsertKeys(), ksAppendKeys(), keyNew(), ksDel()
614 Definition at line 762 of file keyset.c.
616 References _KeySet::end, _Key::next, _KeySet::size, and _KeySet::start.
618 Referenced by commandEdit(), commandList(), and ksCompare().
620 ssize_t ksAppendKeys (KeySet * ks, KeySet * toAppend)
622 Transfers all toAppend contained keys to the end of the ks.
623 After this call, the toAppend KeySet will be empty, and can be deleted
625 with ksDel().
626 Returns:
628 the size of the KeySet after transfer
629 Parameters:
631 ks the KeySet that will receive the keys
632 toAppend the KeySet that provides the keys that will be transfered
633 See also:
635 ksAppend(), ksInsert(), ksInsertKeys()
636 Definition at line 784 of file keyset.c.
638 References _KeySet::cursor, _KeySet::end, _Key::next, _KeySet::size,
640 and _KeySet::start.
641 Referenced by commandList(), and ksCompare().
643 int ksCompare (KeySet * ks1, KeySet * ks2, KeySet * removed)
645 Compare 2 KeySets.
646 This is a c-helper function, you need not implement it in a binding.
648 This method behavior is the following:
650 · A key (by full name) that is present on ks1 and ks2, and has
652 something different, will be transfered from ks2 to ks1, and ks1's
653 (old) version deleted.
654 · Keys present in ks1, but not in ks2 will be transfered from ks1 to
656 removed.
657 · Keys that are keyCompare() equal in ks1 and ks2 will be keyDel()eted
659 from ks2.
660 · Keys present in ks2 but not in ks1 will be transfered to ks1.
662 In the end, ks1 will have all the keys that matter, and ks2 will be
664 empty.
665 After ksCompare(), you should, in this order:
667 1. ksDel(ks2)
669 2. call kdbSetKeys() on ks1 to commit all changed keys
671 3. kdbRemoveKey() for all keys in the removed KeySet
673 4. ksDel(removed)
675 Parameters:
677 ks1 first and main KeySet
678 ks2 second KeySet
679 removed (generally empty) KeySet that will be filled with keys
680 removed from ks1
681 See also:
683 keyCompare()
684 commandEdit() at the KeyDB :: Class Methods command
686 Returns:
688 allways 0
689 Example.RS 4
691 KeySet *ks1,*ks2,*removed;
694 Key *key;
695 ks1=ksNew();
697 ks2=ksNew();
698 removed=ksNew();
699 // ...
701 // Populate ks1 and ks2....
702 // ...
703 ksCompare(ks1,ks2,removed);
705 ksDel(ks2); // second KeySet is allways empty after ksCompare()
707 kdbSetKeys(ks1); // commit changed keys
708 ksDel(ks1); // don't need ks1 anymore
709 // Remove all keys that disapeared from ks1...
711 ksSort(removed); // Sort it first so then we ensure child keys are removed
712 // before their parents
713 while (key=ksPopLast(removed)) {
714 kdbRemoveKey(key);
715 keyDel(key);
716 }
717 ksDel(removed); // free the KeySet memory
719 Definition at line 879 of file keyset.c.
722 References _KeySet::end, KEY_SWITCH_DOMAIN, KEY_SWITCH_NAME,
724 KEY_SWITCH_NEEDSYNC, keyCompare(), keyDel(), ksAppend(),
725 ksAppendKeys(), _Key::next, _KeySet::size, and _KeySet::start.
726 Referenced by commandEdit().
728 ssize_t ksToStream (const KeySet * ks, FILE * stream, unsigned long
730 options)
731 Writes to stream an XML version of the ks object.
732 String generated is of the form:
734 <?xml version="1.0" encoding="UTF-8"?>
736 <!-- Generated by Elektra API. Total of n keys. -->
738 <keyset xmlns="http://www.libelektra.org"
740 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
741 xsi:schemaLocation="http://www.libelektra.org elektra.xsd">
742 <key name=...>...</key>
745 <key name=...>...</key>
746 <key name=...>...</key>
747 </keyset>
749 OR, if KDBOptions::KDB_O_HIER is used, the form will be:
751 <?xml version="1.0" encoding="UTF-8"?>
753 <!-- Generated by Elektra API. Total of n keys. -->
755 <keyset xmlns="http://www.libelektra.org"
757 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
758 xsi:schemaLocation="http://www.libelektra.org elektra.xsd"
759 parent="smallest/parent/name">
761 <key basename=...>...</key>
763 <key name=...>...</key> <!-- a key thats not under this keyset's parent -->
764 <key basename=...>...</key>
765 </keyset>
767 Parameters:
769 stream where to write output: a file or stdout
770 options accepted KDBOptions ORed:
771 · KDBOptions::KDB_O_NUMBERS
773 Do not convert UID and GID into user and group names.
774 · KDBOptions::KDB_O_FULLNAME
776 The user keys are exported with their full names (including user
777 domains)
778 · KDBOptions::KDB_O_CONDENSED
780 Less human readable, more condensed output.
781 · KDBOptions::KDB_O_XMLHEADERS
783 Use it. Include the correct XML headers in the output. If not
784 used, the <?xml?> and schema info inside the <keyset> object will
785 not be generated.
786 · KDBOptions::KDB_O_HIER
788 Will generate a <keyset> node containing a parent attribute, and
789 <key> nodes with a basename relative to that parent. The parent
790 is calculated by taking the smallest key name in the keyset, so
791 it is a good idea to have only related keys on the keyset.
792 Otherwise, a valid consistent XML document still will be
793 generated with regular absolute name attribute for the <key>
794 nodes, due to a clever keyToStreamBasename() implementation.
795 See also:
797 keyToStream()
798 commandList() for usage example
800 Returns:
802 number of bytes written to output, or -1 if some error occurs
803 Definition at line 1029 of file keyset.c.
805 References KDB_O_HIER, KDB_O_XMLHEADERS, keyToStream(),
807 keyToStreamBasename(), ksGetCommonParentName(), _Key::next,
808 _KeySet::size, and _KeySet::start.
809 Referenced by commandEdit(), and commandList().
811 ssize_t ksGetCommonParentName (const KeySet * ks, char *
813 returnedCommonParent, const size_t maxSize)
814 Calculates the common parent to all keys in ks.
815 This is a c-helper function, you need not implement it in bindings.
817 Given the ks KeySet, calculates the parent name for all the keys. So if
819 ks contains this keys:
820 system/sw/xorg/Monitors/Monitor1/vrefresh
822 system/sw/xorg/Monitors/Monitor1/hrefresh
823 system/sw/xorg/Devices/Device1/driver
824 system/sw/xorg/Devices/Device1/mode
825 The common parent is system/sw/xorg .
827 On the other hand, if we have this KeySet:
829 system/some/thing
831 system/other/thing
832 user/unique/thing
833 No common parent is possible, so returnedCommonParent will contain
835 nothing.
836 This method will work correctly only on sorted KeySets .
838 Parameters:
840 returnedCommonParent a pre-allocated buffer that will receive the
841 common parent, if found
842 maxSize size of the pre-allocated returnedCommonParent buffer
843 Returns:
845 size in bytes of the parent name, or 0 if there is no common
846 parent, or a negative number to indicate an error, then errno must
847 be checked.
848 Definition at line 1148 of file keyset.c.
850 References KDB_RET_TRUNC, _Key::key, keyGetNameSize(), _Key::next,
852 _KeySet::start, and strblen().
853 Referenced by ksToStream().
855 void ksSort (KeySet * ks)
857 Sorts a KeySet aphabetically by Key name, using qsort().
858 Parameters:
860 ks KeySet to be sorted
861 Definition at line 1198 of file keyset.c.
863 References _KeySet::end, _Key::next, _KeySet::size, and _KeySet::start.
865 int ksInit (KeySet * ks)
867 KeySet object initializer.
868 You should always use ksNew() instead of ksInit().
870 Every KeySet object that will be used must be initialized first, to
872 setup pointers, counters, etc. After use, all ksInit()ialized KeySets
873 must be cleaned with ksClose().
874 See also:
876 ksNew(), ksClose(), keyInit()
877 Returns:
879 allways 0
880 Definition at line 1239 of file keyset.c.
882 References _KeySet::cursor, _KeySet::end, _KeySet::size, and
884 _KeySet::start.
885 Referenced by ksNew().
887 int ksClose (KeySet * ks)
889 KeySet object cleaner.
890 Will keyDel() all contained keys, reset internal pointers and counters.
892 After this call, the ks object is ready to be freed by you.
894 See also:
896 keyDel(), ksInit(), keyClose()
897 ksAppend() for details on how keys are inserted in KeySets
899 Returns:
901 always 0
902 Definition at line 1258 of file keyset.c.
904 References _KeySet::cursor, _KeySet::end, keyDel(), _Key::next,
906 _KeySet::size, and _KeySet::start.
907 Referenced by ksDel().
909Elektra Project 25 Mar 2007 KeySet :: Class Methods(3)