1KeyDB :: Class Methods(3) Library Functions Manual KeyDB :: Class Methods(3)
2
6 KeyDB :: Class Methods - General methods to access the Key database.
7 Data Structures
10 struct _KDBInfo
11 Object returned by kdbGetInfo() containing some informations about
12 the Elektra library and backend being used.
13 Typedefs
15 typedef _KDBInfo KDBInfo
16 Object returned by kdbGetInfo() containing some informations about
17 the Elektra library and backend being used.
18 Enumerations
20 enum KDBErr { KDB_RET_OK = 0, KDB_RET_NULLKEY = EINVAL,
21 KDB_RET_UNINITIALIZED = EINVAL, KDB_RET_NOTFOUND = ENOENT,
22 KDB_RET_INVALIDKEY = 1001, KDB_RET_NOKEY = 1002, KDB_RET_NODATA =
23 1003, KDB_RET_NODESC = 1004, KDB_RET_NODOMAIN = 1005,
24 KDB_RET_NOGROUP = 1006, KDB_RET_NOTIME = 1007, KDB_RET_NOCRED =
25 EACCES, KDB_RET_TRUNC = ERANGE, KDB_RET_NOMEM = ENOMEM,
26 KDB_RET_TYPEMISMATCH = 1008, KDB_RET_NOSYS = ENOSYS,
27 KDB_RET_EBACKEND = 1009 }
28 Some return codes generated by the Elektra library.
29 enum KDBOptions { KDB_O_RECURSIVE = 1, KDB_O_DIR = 1<<1, KDB_O_DIRONLY
30 = 1<<2, KDB_O_STATONLY = 1<<4, KDB_O_INACTIVE = 1<<5, KDB_O_SORT =
31 1<<6, KDB_O_NFOLLOWLINK = 1<<7, KDB_O_CONDENSED = 1<<8,
32 KDB_O_NUMBERS = 1<<9, KDB_O_XMLHEADERS = 1<<10, KDB_O_FULLNAME =
33 1<<11, KDB_O_FULLUGID = 1<<12, KDB_O_HIER = 1<<13, KDB_O_NOCASE =
34 1<<15, KDB_O_NOSPANPARENT = 1<<16, KDB_O_ALL = 1<<17 }
35 Options to change the default behavior of some methods.
36 Functions
38 int kdbOpen (KDBHandle *handle)
39 Opens the session with the Key database, using a backend defined by
40 environment var $KDB_BACKEND.
41 int kdbOpenDefault (KDBHandle *handle)
42 Opens the session with the Key database.
43 int kdbOpenBackend (KDBHandle *handle, char *backendName)
44 Opens the session with the Key database, dynamically loading a
45 specific beckend for libelektra.so.
46 int kdbClose (KDBHandle *handle)
47 Closes the session with the Key database.
48 ssize_t kdbGetKeyChildKeys (KDBHandle handle, const Key *parentKey,
49 KeySet *returned, unsigned long options)
50 Retrieve a number of inter-related keys at once.
51 int kdbStatKey (KDBHandle handle, Key *key)
52 Stats the key only for its meta-info from the backend storage.
53 int kdbGetKey (KDBHandle handle, Key *key)
54 Fully retrieves the passed key from the backend storage.
55 int kdbSetKeys (KDBHandle handle, KeySet *ks)
56 Commits the ks KeySet to the backend storage, starting from ks's
57 current position until its end.
58 int kdbSetKey (KDBHandle handle, Key *key)
59 Sets key in the backend storage.
60 int kdbRename (KDBHandle handle, Key *key, const char *newName)
61 Rename a key in the backend storage.
62 int kdbRemoveKey (KDBHandle handle, const Key *key)
63 Remove a key from the backend storage.
64 int kdbLink (KDBHandle handle, const char *oldPath, const char
65 *newKeyName)
66 Create a link key on the backend storage that points to other key.
67 uint32_t kdbMonitorKeys (KDBHandle handle, KeySet *interests, uint32_t
68 diffMask, unsigned long iterations, unsigned sleep)
69 Monitor a KeySet for some key change.
70 uint32_t kdbMonitorKey (KDBHandle handle, Key *interest, uint32_t
71 diffMask, unsigned long iterations, unsigned sleep)
72 Monitor a key change.
73 KDBInfo * kdbGetInfo (KDBHandle handle)
74 Returns a structure of information about the internals of the
75 library and the backend used.
76 void kdbFreeInfo (KDBInfo *info)
77 Frees the object returned by kdbGetInfo().
78 int kdbInfoToString (KDBInfo *info, char *string, size_t maxSize)
79 Convenience method to provide a human readable text for what
80 kdbGetInfo() returns.
81 char * kdbStrError (int errnum)
82 Provides an error string associated with errnum.
83 int kdbPrintError (const char *msg)
84 Prints an error message related to errno on standard error,
85 prefixed by msg.
86
88 General methods to access the Key database.
89 To use them:
91 #include <kdb.h>
93 The kdb*() class of methods are used to access the storage, to get and
96 set Keys or KeySets .
97 They use some backend implementation to know the details about how to
99 access the storage. Currently we have this backends:
100 · berkeleydb: the keys are stored in a Berkeley DB database, providing
102 very small footprint, speed, and other advantages.
103 · filesys: the key hierarchy and data are saved as plain text files in
105 the filesystem.
106 · ini: the key hierarchy are saved into configuration files.
108 See also:
110 http://www.libelektra.org/Ini
111 · fstab: a reference backend used to interpret the /etc/fstab file as a
113 set of keys under system/filesystems .
114 · gconf: makes Elektra use the GConf daemon to access keys. Only the
116 user/ tree is available since GConf is not system wide.
117 Backends are physically a library named /lib/libelektra-{NAME}.so .
119 In general usage, the default backend will be used, which is a pointer
121 to some other backend. Your program can use a different backend simply
122 by setting the KDB_BACKEND environment variable. Or, if you know what
123 you are doing, you can hardcode it in your code and use the explicit
124 kdbOpenBackend() method to use one. These options should really not
125 used, thus you destroy the global namespace with that.
126 When writing a new backend , these are the methods you'll have to
128 reimplement: kdbOpen(), kdbClose(), kdbGetKey(), kdbSetKey(),
129 kdbStatKey(), kdbGetKeyChildKeys(), kdbRemove(), kdbRename().
130 And methods that are suggested to reimplement (but not needed) if you
132 want them to get the benefits of your new backend: kdbSetKeys(),
133 kdbMonitorKey(), kdbMonitorKeys().
134 Language binding writers should follow the same rules:
136 · You must relay completely on the backend-dependent methods.
138 · You may use or reimplement the second set of methods.
140 · You should completely reimplement in your language the higher lever
142 methods.
143 · Many methods are just for comfort in C. These methods are marked and
145 need not to be implemented if the binding language has e.g. string
146 operators which can do the operation easily.
147
149 typedef struct _KDBInfo KDBInfo
150 Object returned by kdbGetInfo() containing some informations about the
151 Elektra library and backend being used.
152 You should not allocate or deallocate memory for each of these members.
154 This is a library responsability.
155 See also:
157 kdbGetInfo(), kdbFreeInfo(), kdbInfoToString()
158 commandInfo() of the 'kdb info' command to see it in action
160
162 enum KDBErr
163 Some return codes generated by the Elektra library.
164 These are Elektra specific errors only, that the library sets in errno.
166 Other errors can be generated by system calls that the API uses. Then
167 errno is propagated.
168 The idea is to keep compatibility to POSIX errno system, so each
170 library error code maps to some POSIX E* error. Some mappings realy
171 makes no sense, so to detect Elektra errors use the following error
172 names, and to detect system's, use the naming convetions documented in
173 errno man page.
174 A very robust program should check errno after each API call.
176 See also:
178 kdbGetChildKeys() for an example on how to handle errors
179 Enumerator:
181 KDB_RET_OK
183 No error
184 KDB_RET_NULLKEY
186 Invalid Key object
187 KDB_RET_UNINITIALIZED
189 Object not initilized
190 KDB_RET_NOTFOUND
192 Key was not found
193 KDB_RET_INVALIDKEY
195 Key name is not 'system/something' or 'user/something...'
196 KDB_RET_NOKEY
198 Key has no name
199 KDB_RET_NODATA
201 Key has no data
202 KDB_RET_NODESC
204 Key has no comment/description
205 KDB_RET_NODOMAIN
207 Key has no user domain set
208 KDB_RET_NOGROUP
210 Key has no group
211 KDB_RET_NOTIME
213 Key has no access time set
214 KDB_RET_NOCRED
216 No credentials to access resource
217 KDB_RET_TRUNC
219 Buffer was too small
220 KDB_RET_NOMEM
222 Out of memory
223 KDB_RET_TYPEMISMATCH
225 Failed to convert key data due to data type
226 KDB_RET_NOSYS
228 Backend method not implemented
229 KDB_RET_EBACKEND
231 Error opening backend
232 Definition at line 231 of file kdb.h.
234 enum KDBOptions
236 Options to change the default behavior of some methods.
237 These options should be ORed.
239 See also:
241 kdbGetChildKeys()
242 ksToStream()
244 keyToStream()
246 Enumerator:
248 KDB_O_RECURSIVE
250 Act recursively.
251 KDB_O_DIR
253 Include dir keys in result.
254 KDB_O_DIRONLY
256 Retrieve only directory keys.
257 KDB_O_STATONLY
259 Only stat key, instead of getting entirelly.
260 KDB_O_INACTIVE
262 Do not ignore inactive keys (that name begins with .).
263 KDB_O_SORT
265 Sort keys.
266 KDB_O_NFOLLOWLINK
268 Do not follow symlinks.
269 KDB_O_CONDENSED
271 Compressed XML, not usefull for human eyes.
272 KDB_O_NUMBERS
274 Use numbers intead of user and group names.
275 KDB_O_XMLHEADERS
277 Show also the XML header of the document.
278 KDB_O_FULLNAME
280 Export user keys using full name (e.g. user:username/some/key).
281 KDB_O_FULLUGID
283 Don't supress obvious key UID, GID, and user domain. Affects
284 only user keys.
285 KDB_O_HIER
287 Export to the new hierarchical XML representation using key
288 basename. See ksToStream().
289 KDB_O_NOCASE
291 Ignore case in ksLookup*() methods
292 KDB_O_NOSPANPARENT
294 Don't continue search if end of current folder reached, in
295 ksLookupRE()
296 KDB_O_ALL
298 Restart search, in ksLookup*() from start -> cursor when cursor
299 -> end failed
300 Definition at line 275 of file kdb.h.
302
304 int kdbOpen (KDBHandle * handle)
305 Opens the session with the Key database, using a backend defined by
306 environment var $KDB_BACKEND.
307 If the environment is not set the default backend will be opened.
309 You must always call this method before retrieving or commiting any
311 keys to the database. In the end of the program, after using the key
312 database, you must not forget to kdbClose(). You can use the atexit ()
313 handler for it.
314 This is the best way to have affairs with the key database, unless the
316 program is concerned about security and authentication (e.g. su, login,
317 telnetd, etc), in which kdbOpenDefault() should be used. kdbOpen() is
318 used by the kdb command.
319 The handle parameter will be initialized with an environment, and it
321 should be passed along on any kdb*() method your application calls.
322 You don't need to use any of the kdbOpen*() methods if you only want to
324 manipulate plain in-memory Key or KeySet objects without any affairs
325 with the backend key database,
326 Parameters:
328 handle the key database handler to initialize
329 See also:
331 kdbOpenBackend(), kdbOpenDefault(), kdbClose()
332 Returns:
334 0 on success
335 -1 on failure and errno is propagated from kdbOpenBackend() using
337 kdbOpen.
338 Definition at line 200 of file libelektra/kdb.c.
340 References kdbOpenBackend().
342 Referenced by commandExport(), and main().
344 int kdbOpenDefault (KDBHandle * handle)
346 Opens the session with the Key database.
347 Different from kdbOpen(), kdbOpenDefault() will completely ignore the
349 $KDB_BACKEND environment and open the default backend. So
350 kdbOpenDefault() must be used by programs concerned about security
351 (e.g. su, login, sshd, etc).
352 The default backend use to be a symlink to the real backend, and is
354 found in /lib/libelektra-default.so
355 The handle parameter will be initialized with an environment, and it
357 should be passed along on any kdb*() method your application calls.
358 Parameters:
360 handle the key database handler to initialize
361 See also:
363 kdbOpen(), kdbOpenBackend(), kdbClose()
364 Returns:
366 0 on success
367 -1 on failure and is set using kdbOpen.
369 Definition at line 231 of file libelektra/kdb.c.
371 References kdbOpenBackend().
373 int kdbOpenBackend (KDBHandle * handle, char * backendName)
375 Opens the session with the Key database, dynamically loading a specific
376 beckend for libelektra.so.
377 After dynamic loading, the backend will be initialized with its
379 implementation of kdbOpen().
380 The handle parameter will be initialized with an environment, and it
382 should be passed along on any kdb*() method your application calls.
383 Parameters:
385 handle the key database handler to initialize
386 backendName used to define the module filename as
387 libelektra-'backendName'.so
388 Returns:
390 0 on success.
391 -1 on failure and errno is set to
393 · KDBErr::KDB_RET_EBACKEND if backend library could not be opened
395 · KDBErr::KDB_RET_NOSYS if backend library doesn't provide the
397 essential 'kdbBackendFactory' initialization symbol
398 · KDBErr::KDB_RET_NOSYS if backend failed to export its methods
400 · KDBErr::KDB_RET_NOSYS if backend does not provide a kdbOpen()
402 implementation
403 See also:
405 kdbOpen()
406 Example of copying keys from one backend to another.RS 4
408 KeySet *ks=ksNew();
411 KDBHandle handle;
412 kdbOpen(&handle); // open default backend
414 kdbGetChildKeys(handle,'system/sw/httpd',ks,
415 KDB_O_NFOLLOWLINK | // we want real links, not their targets
416 KDB_O_INACTIVE | // even commented (inactive) keys
417 KDB_O_DIR | // even pure directory keys
418 KDB_O_RECURSIVE | // all of this recursivelly
419 KDB_O_SORT); // sort all
420 kdbClose(&handle);
421 kdbOpenBackend(&handle,'apache');
423 // The hipotethical libelektra-apache.so backend implementation for kdbSetKeys()
425 // simply interprets the passed KeySet and generates an old style
426 // equivalent /etc/httpd/httpd.conf file.
427 kdbSetKeys(handle,ks);
428 kdbClose(&handle);
429 ksDel(ks);
431 Emulating same bahavior of previous example but now with the kdb
434 command.RS 4
435 bash# kdb export system/sw/httpd > apacheconf.xml
438 bash# KDB_BACKEND=apache kdb import apacheconf.xml
439 Definition at line 291 of file libelektra/kdb.c.
442 References KDB_RET_EBACKEND, KDB_RET_NOSYS, kdbBackendFactory(), and
444 kdbhSetUserName().
445 Referenced by kdbOpen(), and kdbOpenDefault().
447 int kdbClose (KDBHandle * handle)
449 Closes the session with the Key database.
450 You should call this method when you finished your affairs with the key
452 database. You can manipulate Key and KeySet objects also after
453 kdbClose(). You must not use any kdb* call afterwards. You can
454 implement kdbClose() in the atexit() handler.
455 This is the counterpart of kdbOpen().
457 The handle parameter will be finalized and all resources associated to
459 it will be freed. After a kdbClose(), this handle can't be used
460 anymore, unless it gets initialized again with another call to
461 kdbOpen().
462 Parameters:
464 handle the key database handler to initialize
465 See also:
467 kdbOpen()
468 Returns:
470 0 on success
471 -1 on failure, and errno is set. If the backend implementation of
473 kdbOpen can't be found, errno is set to KDBErr::KDB_RET_NOSYS.
474 Definition at line 379 of file libelektra/kdb.c.
476 References KDB_RET_NOSYS.
478 Referenced by commandExport(), and main().
480 ssize_t kdbGetKeyChildKeys (KDBHandle handle, const Key * parentKey, KeySet
482 * returned, unsigned long options)
483 Retrieve a number of inter-related keys at once.
484 This is one of the most practical methods of the library, and you
486 should use it to retrieve in one shot all keys needed by your
487 application.
488 The returned KeySet must be initialized or may already contain some
490 keys (in this case, the new retrieved keys will be simply appended).
491 In default behaviour (options = 0) it will fully retrieve all keys
493 under the parentKey folder, except folders (and their children) and
494 inactive keys.
495 The parent key per se will not be retrieved. This is the job of the
497 caller.
498 The option is an array of the following ORed flags:
500 · KDBOptions::KDB_O_RECURSIVE
502 Retrieve also the keys under the folder keys, under the specified
503 parentKey, recursively.
504 · KDBOptions::KDB_O_DIR
506 Also include folders in the returned KeySet, otherwise only value
507 keys will be retrieved.
508 · KDBOptions::KDB_O_DIRONLY
510 Put in returned only the folder keys. The resulting KeySet will be
511 only the skeleton of the tree. This option must be ORed together with
512 KDB_O_DIR.
513 · KDBOptions::KDB_O_STATONLY
515 Only stat the keys. It means that key value, comment and data type
516 will not be retrieved. The resulting keys will contain only meta info
517 such as user and group IDs, owner, access permissions and
518 modification times.
519 · KDBOptions::KDB_O_INACTIVE
521 Will make it not ignore inactive keys, so returned will contain also
522 inactive keys. Inactive keys are those that have names begining with
523 '.' (dot).
524 · KDBOptions::KDB_O_SORT
526 Causes returned to be ksSort()ed.
527 Example:.RS 4
529 char errormsg[300];
532 KDBHandle handle;
533 KeySet *myConfig;
534 Key *key;
535 key=keyNew('system/sw/MyApp',KEY_SWITCH_END);
537 myConfig=ksNew();
538 kdbOpen(&handle);
540 rc=kdbGetKeyChildKeys(handle,key, myConfig, KDB_O_RECURSIVE);
541 keyDel(key); // free this resource.... we'll use it later
542 kdbClose(&handle);
543 // Check and handle propagated error
545 if (rc) switch (errno) {
546 case KDB_RET_INVALIDKEY:
547 sprintf(errormsg,'Something invalid');
548 kdbPrintError(errormsg);
549 break;
550 case KDB_RET_NOTFOUND:
551 fprintf(stderr,'Key not found'); // custom error message
552 break;
553 default:
554 sprintf(errormsg,'My application');
555 kdbPrintError(errormsg);
556 break;
557 }
558 ksRewind(myConfig); // go to begining of KeySet
560 key=ksNext(myConfig);
561 while (key) {
563 // do something with each key . . .
564 key=ksNext(myConfig); // next key
566 }
567 Parameters:
570 parentKey parent key
571 returned the (pre-initialized) KeySet returned with all keys found
572 options ORed options to control approaches
573 See also:
575 KDBOptions, KDBErr
576 kdbGetChildKeys() for a convenience method
578 ksLookupByName(), ksLookupRE(), ksLookupByValue() for powerfull
580 lookups after the KeySet was retrieved
581 ksSort() for what is done when you ask for KDBOptions::KDB_O_SORT
583 commandList() code in KeyDB :: Class Methods command for usage
585 example
586 commandEdit() code in KeyDB :: Class Methods command for usage
588 example
589 commandExport() code in KeyDB :: Class Methods command for usage
591 example
592 Returns:
594 number of keys contained by returned or -1 on failure, errno is
595 propagated and can be KDBErr::KDB_RET_INVALIDKEY,
596 KDBErr::KDB_RET_NOTFOUND, KDBErr::KDB_RET_NOSYS
597 Definition at line 496 of file libelektra/kdb.c.
599 References KDB_RET_NOSYS.
601 Referenced by commandList(), and kdbGetChildKeys().
603 int kdbStatKey (KDBHandle handle, Key * key)
605 Stats the key only for its meta-info from the backend storage.
606 The key may not hold value and comment after using kdbStatKey().
608 A key of type KeyType::KEY_TYPE_LINK will have its target address
610 loaded in the key structure, which can be accessed later using
611 keyStealValue() or keyGetString(). This is the only way to know the
612 target of a link key without dereferencing it (in contrast to
613 kdbGetKey(), where the link is followed).
614 Info like comments and key data type may not be retrieved if backend
616 supports a way not to get them.
617 Parameters:
619 key an initialized Key pointer to be filled.
620 Returns:
622 0 on success
623 -1 on failure and errno is propagated
625 Definition at line 527 of file libelektra/kdb.c.
627 References KDB_RET_NOSYS.
629 Referenced by commandList().
631 int kdbGetKey (KDBHandle handle, Key * key)
633 Fully retrieves the passed key from the backend storage.
634 The backend will try to get the key, identified through its name.
636 Parameters:
638 key a pointer to a Key that has a name set
639 Returns:
641 0 on success
642 -1 on failure and errno is propagated
644 See also:
646 commandGet() code in KeyDB :: Class Methods command for usage
647 example
648 Definition at line 554 of file libelektra/kdb.c.
650 References KDB_RET_NOSYS.
652 Referenced by commandEdit(), commandGet(), commandList(), commandSet(),
654 kdbGetKeyByParent(), kdbGetKeyByParentKey(), kdbGetValue(),
655 kdbMonitorKey_default(), kdbSetValue(), and keyNew().
656 int kdbSetKeys (KDBHandle handle, KeySet * ks)
658 Commits the ks KeySet to the backend storage, starting from ks's
659 current position until its end.
660 This is why it is suggested that you call ksRewind() on ks before
662 calling this method.
663 Each key is checked with keyNeedsSync() before being actually commited.
665 So only changed keys are updated.
666 If some error occurs, kdbSetKeys() will stop. In this situation the
668 KeySet internal cursor is left on the key that generated the error.
669 Example of how this method must be used:.RS 4
671 KeySet *ks; // the KeySet I want to set
674 // ommited... fill ks with some keys
676 ksRewind(ks);
678 while ((ret=kdbSetKeys(handle,ks))) {
679 // We got an error. Warn user.
680 Key *problem;
681 char error[500]='';
682 char keyname[300]='';
683 problem=ksCurrent(ks);
685 if (problem) keyGetFullName(problem,keyname,sizeof(keyname));
686 sprintf(error,'kdb import: while importing %s', keyname);
687 kdbPrintError(error);
688 // And try to set keys again starting from the next key,
690 // unless we reached the end of KeySet
691 if (ksNext(ks) == 0) break;
692 }
693 Parameters:
696 ks a KeySet full of changed keys
697 Returns:
699 0 on success
700 -1 on failure and errno is propagated
702 See also:
704 kdbSetKey(), keyNeedsSync(), ksNext(), ksCurrent()
705 commandEdit(), commandImport() code in KeyDB :: Class Methods
707 command for usage and error handling example
708 Definition at line 611 of file libelektra/kdb.c.
710 References KDB_RET_NOSYS, and kdbSetKeys_default().
712 Referenced by commandEdit(), and commandImport().
714 int kdbSetKey (KDBHandle handle, Key * key)
716 Sets key in the backend storage.
717 Directory keys will be created recursivelly if needed. In case a path
719 component is found in the storage as a regular non-dir key, it will be
720 converted into a dir key if possible.
721 See also:
723 kdbGetKey(), kdbSetKeys()
724 commandSet() code in KeyDB :: Class Methods command for usage
726 example
727 Returns:
729 0 on success
730 -1 on failure and errno is propagated
732 Definition at line 644 of file libelektra/kdb.c.
734 References KDB_RET_NOSYS.
736 Referenced by commandSet(), kdbLink(), kdbRename_default(),
738 kdbSetKeys_default(), and kdbSetValue().
739 int kdbRename (KDBHandle handle, Key * key, const char * newName)
741 Rename a key in the backend storage.
742 key must be a fully retrieved key. If you want another name its not
744 enough to kdbSetKey() it again (old key would stay, you could remove it
745 with kdbRemoveKey though).
746 kdbRename() can do it for you, maybe with a more efficient method then
748 described above.
749 Parameters:
751 key the key to be renamed
752 newName the new key name
753 Returns:
755 0 on success
756 -1 on failure and errno is propagated
758 Definition at line 676 of file libelektra/kdb.c.
760 References KDB_RET_NOSYS, and kdbRename_default().
762 Referenced by commandMove().
764 int kdbRemoveKey (KDBHandle handle, const Key * key)
766 Remove a key from the backend storage.
767 The key object will not be freed. It is your responsability to keyDel()
769 it after kdbRemoveKey().
770 This method is not recursive.
772 Parameters:
774 key the key to be removed
775 Returns:
777 0 on success
778 -1 on failure and errno is propagated
780 See also:
782 commandRemove(), and ksCompare() code in KeyDB :: Class Methods
783 command for usage example
784 Definition at line 709 of file libelektra/kdb.c.
786 References KDB_RET_NOSYS.
788 Referenced by kdbRemove(), and kdbRename_default().
790 int kdbLink (KDBHandle handle, const char * oldPath, const char *
792 newKeyName)
793 Create a link key on the backend storage that points to other key.
794 Parameters:
796 oldPath destination key name
797 newKeyName name of the key that will be created and will point to
798 oldPath
799 Returns:
801 whathever is returned by kdbSetKey(), and errno is set
802 See also:
804 commandLink() code in KeyDB :: Class Methods command for usage
805 example
806 commandSet() code in KeyDB :: Class Methods command for usage
808 example
809 Definition at line 736 of file libelektra/kdb.c.
811 References kdbSetKey(), KEY_SWITCH_END, keyDel(), keyNew(), and
813 keySetLink().
814 Referenced by commandLink().
816 uint32_t kdbMonitorKeys (KDBHandle handle, KeySet * interests, uint32_t
818 diffMask, unsigned long iterations, unsigned sleep)
819 Monitor a KeySet for some key change.
820 This method will scan the interests KeySet, starting and finishing in
822 the KeySet's next cursor position, in a circular behavior, looking for
823 some change defined in the diffMask mask. It will use kdbMonitorKey()
824 and will return at the first key change ocurrence, or when requested
825 iterations finish.
826 You may check the return code to see if some key changed, and get the
828 updated key using ksCurrent().
829 Example:.RS 4
831 KeySet *myConfigs;
834 // key db initialization omitted
836 myConfigs=ksNew();
838 kdbGetChildKeys(handle,'system/sw/MyApp',myConfigs,KDB_O_RECURSIVE | KDB_O_SORT);
839 // use the keys . . . .
841 // now monitor any key change
843 ksRewind(myConfigs);
844 while (1) {
845 Key *changed=0;
846 char keyName[300];
847 char keyData[300];
848 uint32_t diff;
849 // block until any change in key value or comment . . .
851 diff=kdbMonitorKeys(handle,myConfigs,
852 KEY_SWITCH_VALUE | KEY_SWITCH_COMMENT,
853 0,0); // ad-infinitum
854 changed=ksCurrent(myConfigs);
856 keyGetName(changed,keyName,sizeof(keyName));
857 switch (diff) {
859 case KEY_SWITCH_FLAG:
860 printf('Key %s was deleted0,keyName);
861 break;
862 case KEY_SWITCH_NEEDSYNC:
863 printf('No cretentials to access Key %s0,keyName);
864 break;
865 default:
866 keyGetString(changed,keyData,sizeof(keyData));
867 printf('Key %s has changed its value to %s0,keyName,keyData);
868 }
869 }
870 ksDel(myConfigs);
872 See also:
875 kdbMonitorKey(), ksCurrent(), ksRewind(), ksNext(), KeySwitch
876 commandMonitor() code in KeyDB :: Class Methods command for usage
878 example
879 Returns:
881 diff mask on success
882 -1 on failure and errno is propagated
884 Definition at line 814 of file libelektra/kdb.c.
886 References KDB_RET_NOSYS, and kdbMonitorKeys_default().
888 uint32_t kdbMonitorKey (KDBHandle handle, Key * interest, uint32_t
890 diffMask, unsigned long iterations, unsigned sleep)
891 Monitor a key change.
892 This method will block execution until one of the folowing happens:
894 · All requested iterations, with requested sleep times, finish. If no
896 change happens, zero is returned.
897 · Requested key info and meta-info (defined by diffMask) changes when
899 keyCompare()ed with the original interest.
900 interest should be a full key with name, value, comments, permissions,
902 etc, and all will be compared and then masked by diffMask.
903 If interest is a folder key, use KEY_SWITCH_TIME in diffMask to detect
905 a time change, so you'll know something happened (key modification,
906 creation, deletion) inside the folder.
907 If interest was not found, or deleted, the method will return
909 immediatly a KEY_SWITCH_FLAG value.
910 If you don't have access rights to interest, the method will return
912 immediatly a KEY_SWITCH_NEEDSYNC value.
913 If something from diffMask has changed in interest, it will be updated,
915 so when method returns, you'll have an updated version of the key.
916 Parameters:
918 interest key that will be monitored
919 diffMask what particular info change we are interested
920 iterations how many times to test. 0 means infinitum or until some
921 change happens
922 sleep time to sleep, in microseconds, between iterations. 0
923 defaults to 1 second.
924 Returns:
926 the ORed KEY_SWITCH_* flags of what changed
927 0 on success
929 -1 on failure and errno is propagated
931 See also:
933 KeySwitch
934 keyCompare()
936 kdbMonitorKeys() to monitor KeySets, and for a code example
938 commandMonitor() code in KeyDB :: Class Methods command for usage
940 example
941 Definition at line 918 of file libelektra/kdb.c.
943 References KDB_RET_NOSYS, and kdbMonitorKey_default().
945 Referenced by commandMonitor(), and kdbMonitorKeys_default().
947 KDBInfo* kdbGetInfo (KDBHandle handle)
949 Returns a structure of information about the internals of the library
950 and the backend used.
951 Currently, the returned object has the following members:
953 · version: the version for the Elektra library
955 · backendName: the name of the storage backend that is or will be used
957 · backendIsOpen: whether the backend was already opened with kdbOpen()
959 After use, the returned object must be freed with a call to
961 kdbFreeInfo().
962 Example:.RS 4
964 KDBInfo *info=0;
967 // key dababase initialization omitted
969 info=kdbGetInfo(handle);
971 printf('The library version I'm using is %s0,info->version);
972 kdbFreeInfo(info);
974 Returns:
977 0 on sucess, -1 if info is NULL, -2 if incompatible app version
978 See also:
980 kdbInfoToString(), kdbFreeInfo(), commandInfo()
981 Definition at line 968 of file libelektra/kdb.c.
983 References _KDBInfo::backendIsOpen, _KDBInfo::backendName, and
985 _KDBInfo::version.
986 Referenced by commandInfo().
988 void kdbFreeInfo (KDBInfo * info)
990 Frees the object returned by kdbGetInfo().
991 This method is provided so the programmer doesn't need to learn about
993 the storage internals of the KDBInfo structure.
994 Parameters:
996 info the structure returned by kdbGetInfo()
997 See also:
999 kdbGetInfo(), kdbInfoToString(), commandInfo()
1000 Definition at line 1003 of file libelektra/kdb.c.
1002 int kdbInfoToString (KDBInfo * info, char * string, size_t maxSize)
1004 Convenience method to provide a human readable text for what
1005 kdbGetInfo() returns.
1006 It is your responsability to allocate and free the string buffer.
1008 Currently, 200 bytes is a good size for a buffer.
1009 Example:.RS 4
1011 KDBInfo *info=0;
1014 char buffer[200];
1015 // key dababase initialization omitted
1017 info=kdbGetInfo(handle);
1019 kdbInfoToString(info,buffer,sizeof(buffer));
1020 printf('Follows some information about Elektra:0);
1021 printf(buffer);
1022 printf('0);
1023 kdbFreeInfo(info);
1025 Parameters:
1028 info the object returned by kdbGetInfo()
1029 string a pre-allocated buffer to fill with human readable
1030 information
1031 maxSize the size of the string buffer, to avoid memory problems
1032 Returns:
1034 0 on success, -1 if info is NULL
1035 See also:
1037 kdbGetInfo(), kdbFreeInfo(), commandInfo()
1038 Definition at line 1274 of file libelektra/kdb.c.
1040 References _KDBInfo::backendIsOpen, _KDBInfo::backendName, and
1042 _KDBInfo::version.
1043 Referenced by commandInfo().
1045 char* kdbStrError (int errnum)
1047 Provides an error string associated with errnum.
1048 Returns:
1050 an error string associated with errnum.
1051 See also:
1053 kdbPrintError()
1054 Definition at line 38 of file error.c.
1056 References KDB_RET_EBACKEND, KDB_RET_INVALIDKEY, KDB_RET_NODATA,
1058 KDB_RET_NODESC, KDB_RET_NODOMAIN, KDB_RET_NOGROUP, KDB_RET_NOKEY,
1059 KDB_RET_NOSYS, KDB_RET_NOTIME, and KDB_RET_TYPEMISMATCH.
1060 Referenced by kdbPrintError().
1062 int kdbPrintError (const char * msg)
1064 Prints an error message related to errno on standard error, prefixed by
1065 msg.
1066 See also:
1068 kdbStrError()
1069 example on kdbGetKeyChildKeys()
1071 Definition at line 71 of file error.c.
1073 References kdbStrError().
1075 Referenced by commandEdit(), commandGet(), commandImport(),
1077 commandLink(), commandList(), commandMove(), commandRemove(), and
1078 commandSet().
1079Elektra Project 25 Mar 2007 KeyDB :: Class Methods(3)