Provided by: elektra-doc_0.7.1-1_all bug

NAME

       KDB :: Low Level Methods -

       General methods to access the Key database.

   Functions
       int kdbMount (KDB *handle, const Key *mountpoint, const KeySet *config)
       int kdbUnmount (KDB *handle, const Key *mountpoint)
       Key * kdbGetMountpoint (KDB *handle, const Key *where)
       KDB * kdbOpen ()
       int kdbClose (KDB *handle)
       ssize_t kdbGet (KDB *handle, KeySet *returned, Key *parentKey, option_t
           options)
       ssize_t kdbSet (KDB *handle, KeySet *ks, Key *parentKey, option_t
           options)

Detailed Description

       General methods to access the Key database.

       To use them:

        #include <kdb.h>

       The kdb*() class of methods are used to access the storage, to get and
       set Keys  or KeySets .

       The most important functions are:

       o kdbOpen()

       o kdbClose()

       o kdbGet()

       o kdbSet()

       The two essential functions for dynamic information about backends are:

       o kdbGetMountpoint()

       o kdbGetCapability()

       They use some backend implementation to know the details about how to
       access the storage. Currently we have this backends:

       o berkeleydb: the keys are stored in a Berkeley DB database, providing
         very small footprint, speed, and other advantages.

       o filesys: the key hierarchy and data are saved as plain text files in
         the filesystem.

       o ini: the key hierarchy are saved into configuration files.

       See also:
           http://www.libelektra.org/Ini

       o fstab: a reference backend used to interpret the /etc/fstab file as a
         set of keys under system/filesystems .

       o gconf: makes Elektra use the GConf daemon to access keys. Only the
         user/ tree is available since GConf is not system wide.

       Backends are physically a library named /lib/libelektra-{NAME}.so.

       See writing a new backend  for information about how to write a
       backend.

       Language binding writers should follow the same rules:

       o You must relay completely on the backend-dependent methods.

       o You may use or reimplement the second set of methods.

       o You should completely reimplement in your language the higher lever
         methods.

       o Many methods are just for comfort in C. These methods are marked and
         need not to be implemented if the binding language has e.g. string
         operators which can do the operation easily.

Function Documentation

   int kdbClose (KDB *handle) Closes the session with the Key database.
       You should call this method when you finished your affairs with the key
       database. You can manipulate Key and KeySet objects also after
       kdbClose(). You must not use any kdb* call afterwards. You can
       implement kdbClose() in the atexit() handler.

       This is the counterpart of kdbOpen().

       The handle parameter will be finalized and all resources associated to
       it will be freed. After a kdbClose(), this handle can't be used
       anymore, unless it gets initialized again with another call to
       kdbOpen().

       See also:
           kdbOpen()

       Parameters:
           handle contains internal information of opened  key database

       Returns:
           0 on success

           -1 on NULL pointer

   ssize_t kdbGet (KDB *handle, KeySet *returned, Key *parentKey,
       option_toptions) Retrieve keys in an atomic and universal way, all
       other kdbGet Functions rely on that one.
       The returned KeySet must be initialized or may already contain some
       keys. The new retrieved keys will be appended using ksAppendKey().

       In default behaviour (options = 0) it will fully retrieve all keys
       under the parentKey folder, with all subfolders and their children but
       not inactive keys or folders.

       The keyset will not be sorted at first place, but will be marked dirty
       and sorted afterwards when needed. That could be a subsequent
       ksLookup(), ksLookupByName() or kdbSet(). See ksSort() on that issue.

       The behaviour can be fine-tuned with options in various ways to make
       kdbGet() more comfortable.

Options

       The option is an array of the following ORed flags:

       o option_t::KDB_O_DEL
          Its often useful to keyDel() the parentKey in the line after
         kdbGet(). Using this flag, you can just pass a key allocated with
         keyNew(), kdbGet() will free it for you in the end.

       o option_t::KDB_O_POP
          The parentKey itself will always be added to returned. If you only
         want the children of the parentKey in returned, but not the parentKey
         itself, use this flag. This is only valid for the first parentKey,
         the one you passed. The other recursive parentKeys will stay in the
         keyset. To get only the leaves of the tree, without any parentKey,
         see option_t::KDB_O_NODIR below.

       o option_t::KDB_O_NODIR
          Don't include folders in the returned KeySet, so only keys without
         subkeys. You can picture it best that you only get the leaves of the
         tree of keys.

       o option_t::KDB_O_DIRONLY
          Put in returned only the folder keys. The resulting KeySet will be
         only the skeleton of the tree. This option must not be ORed together
         with KDB_O_DIR.

       o option_t::KDB_O_NOSTAT
          Don't stat they keys, whatever keyNeedStat() says. That means that
         also the key value and comment will be retrieved. The flag will
         result in that all keys in returned don't have keyNeedStat() set.

       o option_t::KDB_O_STATONLY
          Only stat the keys. It means that key value and comment will not be
         retrieved. The resulting keys will contain only meta info such as
         user and group IDs, owner, mode permissions and modification times.
         You don't need that flag if the keys already have keyNeedStat() set.
         The flag will result in that all keys in returned have keyNeedStat()
         set.

       o option_t::KDB_O_INACTIVE
          Will make it not ignore inactive keys, so returned will contain also
         inactive keys. Inactive keys are those that have names beginning with
         '.' (dot). Please be sure that you know what you are doing, inactive
         keys must not have any semantics to the application. This flag should
         only be set in key browsers after explicit user request. You might
         also get inactive keys when you plan to remove a whole hierarchy.

       o option_t::KDB_O_SORT
          Force returned to be ksSort()ed. Normally you don't want that the
         returned is sorted immediately because you might add other keys or go
         for another kdbGet(). Sorting will take place automatically when
         needed by ksLookup() or kdbSet(), also without this option set. But
         you need to sort the keyset for yourself, when you just iterate over
         it. If you want to do that, pass this flag at the last kdbGet().

       o option_t::KDB_O_NORECURSIVE
          Don't get the keys recursive. Only receive keys from one folder.
         This might not work if the backend does not support it. Be prepared
         for more keys and use ksLookup() and avoid static assumptions on how
         many keys you get.

       Example:

           KDB *handle;
           KeySet *myConfig;
           Key *key;

           myConfig=ksNew(0);

           handle = kdbOpen();

           key=keyNew('system/sw/MyApp',KEY_END);
           rc=kdbGet(handle,key, myConfig, 0);
           keyDel(key);

           key=keyNew('user/sw/MyApp',KEY_END);
           rc=kdbGet(handle,key, myConfig, 0);
           keyDel(key);

           // will sort keyset here
           key=ksLookupByName(myConfig,'/sw/MyApp/key', 0);
           // check if key is not 0 and work with it...

           ksDel (myConfig); // delete the in-memory configuration

           // maybe you want kdbSet() myConfig here

           kdbClose(handle); // no more affairs with the key database.

Details

       When no backend could be found (e.g. no backend mounted) the default
       backend will be used.

       If you pass a NULL pointer as handle and/or returned kdbGet() will
       return -1 and do nothing but keyDel() the parentKey when requested and
       not a NULL pointer.

       If you pass NULL as parentKey the root keys of all namespaces will be
       appended to returned.

       For every directory key (keyIsDir()) the appropriate backend will be
       chosen and keys in it will be requested.

       If any backend reports an failure the recursive getting of keys will be
       stopped. Backends only report failure when they are not able to get
       keys for any problems.

       Parameters:
           handle contains internal information of opened  key database
           parentKey parent key or NULL to get the root keys
           returned the (pre-initialized) KeySet returned with all keys found
           options ORed options to control approaches

       See also:
           #option_t

           kdb higher level Methods  that rely on kdbGet()

           ksLookupByName(), ksLookupByString() for powerful lookups after the
           KeySet was retrieved

           commandList() code in KDB :: Low Level Methods command for usage
           example

           commandEdit() code in KDB :: Low Level Methods command for usage
           example

           commandExport() code in KDB :: Low Level Methods command for usage
           example

       Returns:
           number of keys contained by returned

           -1 on failure

   Key* kdbGetMountpoint (KDB *handle, const Key *where) Lookup a mountpoint
       in a handle for a specific key.
       Will return a key representing the mountpoint or null if there is no
       appropriate mountpoint e.g. its the root mountpoint.

       Together with kdbGetCapability() the two essential information about
       mounted backends.

       Example:

           Key * key = keyNew ('system/template');
           KDB * handle = kdbOpen();
           Key *mountpoint=0;
           mountpoint=kdbGetMountpoint(handle, key);

           printf('The library I am using is %s mounted in %s0,
                   keyValue(mountpoint),
                   keyName(mountpoint));
           kdbClose (handle);
           keyDel (key);

       Parameters:
           handle is the data structure, where the mounted directories are
           saved.
           where the key, that should be looked up.

       Returns:
           the mountpoint associated with the key

   int kdbMount (KDB *handle, const Key *mountpoint, const KeySet *config)
       Dynamically mount a single backend.
       Maps the mountpoint, defined through its name and value, into the
       global elektra hierarchy. If successfull, under the mountpoint another
       backend will reside.

       This only works for a single KDB, that means a single thread in a
       single process. You may want statically mounting by editing
       system/elektra/mountpoints.

       If you allocated mountpoint and config first, make sure that you free
       it! It is ok to free it immediately afterwards.

       Parameters:
           handle handle to the kdb data structure
           mountpoint the keyName() of this key is the mountpoint, keyValue()
           the backend
           config the configuration passed for that backend

       Returns:
           0 on success, -1 if an error occurred

   KDB* kdbOpen (void) Opens the session with the Key database.
       The first step is to open the default backend. With it
       system/elektra/mountpoints will be loaded and all needed libraries and
       mountpoints will be determined. These libraries for backends will be
       loaded and with it the KDB datastructure will be initialized.

       You must always call this method before retrieving or committing any
       keys to the database. In the end of the program, after using the key
       database, you must not forget to kdbClose(). You can use the atexit ()
       handler for it.

       The pointer to the KDB structure returned will be initialized like
       described above, and it must be passed along on any kdb*() method your
       application calls.

       Get a KDB handle for every thread using elektra. Don't share the handle
       across threads, and also not the pointer accessing it:

       thread1 {
               KDB * h;
               h = kdbOpen();
               // fetch keys and work with them
               kdbClose(h);
       }
       thread2 {
               KDB * h;
               h = kdbOpen();
               // fetch keys and work with them
               kdbClose(h);
       }

       You don't need to use the kdbOpen() if you only want to manipulate
       plain in-memory Key or KeySet objects without any affairs with the
       backend key database,

       See also:
           kdbClose() to end all affairs to the Key :: Basic Methods database.

       Returns:
           a KDB pointer on success

           NULL on failure

   ssize_t kdbSet (KDB *handle, KeySet *ks, Key *parentKey, option_toptions)
       Set keys in an atomic and universal way, all other kdbSet Functions
       rely on that one.
       The given handle and keyset are the objects to work with.

       With parentKey you can only store a part of the given keyset. Otherwise
       pass a null pointer or a parentKey without a name.

       KeySet *ks = ksNew(0);
       kdbGet (h, ks, keyNew('system/myapp',0), KDB_O_DEL);
       kdbGet (h, ks, keyNew('user/myapp',0), KDB_O_DEL);

       //now only set everything below user, because you can't write to system
       kdbSet (h, ks, keyNew('user/myapp',0), KDB_O_DEL);

       ksDel (ks);

       Each key is checked with keyNeedSync() before being actually committed.
       So only changed keys are updated. If no key of a backend needs to be
       synced the kdbSet_backend() will be omitted.

       If some error occurs, kdbSet() will stop. In this situation the KeySet
       internal cursor will be set on the key that generated the error. This
       specific key and all behind it were not set. To be failsafe jump over
       it and try to set the rest, but report the error to the user.

       Example of how this method can be used:

           int i;
           KeySet *ks;  // the KeySet I want to set
           // fill ks with some keys
           for (i=0; i< 10; i++) // limit to 10 tries
           {
                   ret=kdbSet(handle,ks, 0, 0);
                   if (ret == -1)
                   {
                           // We got an error. Warn user.
                           Key *problem;
                           problem=ksCurrent(ks);
                           if (problem)
                           {
                                   char keyname[300]='';
                                   keyGetFullName(problem,keyname,sizeof(keyname));
                                   fprintf(stderr,'kdb import: while importing %s', keyname);
                           } else break;
                           // And try to set keys again starting from the next key,
                           // unless we reached the end of KeySet
                           if (ksNext(ks) == 0) break;
                   }
           }

Options

       There are some options changing the behaviour of kdbSet():

       o option_t::KDB_O_DEL
          Its often useful to keyDel() the parentKey in the line after
         kdbGet(). Using this flag, you can just pass a key allocated with
         keyNew(), kdbGet() will free it for you in the end.

       o option_t::KDB_O_SYNC
          Will force to save all keys, independent of their sync state.

       o option_t::KDB_O_NOREMOVE
          Don't remove any key from disk, even if keyRemove() was set. With
         that flag removing keys can't happen unintentional. The flag will
         result in that all keys in returned don't have keyNeedRemove() set.

       o option_t::KDB_O_REMOVEONLY
          Remove all keys instead of setting them. All keys in returned will
         have keyNeedRemove() set, but not keyNeedStat() saying to you that
         the key was deleted permanently. This option implicit also activates
         option_t::KDB_O_SYNC because the sync state will be changed when they
         are marked remove. You might need option_t::KDB_O_INACTIVE set for
         the previous call of kdbGet() if there are any. Otherwise the
         recursive remove will fail, because removing directories is only
         possible when all subkeys are removed.

Details

       When you don't have a parentKey or its name empty, then all keys will
       be set.

       You can remove some keys instead of setting them by marking them with
       keyRemove(). The keyNeedSync() flag will be unset after successful
       removing. But the keyNeedRemove() flag will stay, but its safe to
       delete the key.

       Parameters:
           handle contains internal information of opened  key database
           ks a KeySet which should contain changed keys, otherwise nothing is
           done
           parentKey holds the information below which key keys should be set
           options see in kdbSet() documentation

       Returns:
           0 on success

           -1 on failure

       See also:
           keyNeedSync(), ksNext(), ksCurrent()

           keyRemove(), keyNeedRemove()

           commandEdit(), commandImport() code in KDB :: Low Level Methods
           command for usage and error handling example

   int kdbUnmount (KDB *handle, const Key *mountpoint) Dynamically unmount a
       single backend.
       Unmount a backend that was mounted with kdbMount() before.

       Parameters:
           handle handle to the kdb data structure
           mountpoint directory where backend is mounted to, that should be
           unmounted

       Returns:
           0 on success, -1 if an error ocurred.

Author

       Generated automatically by Doxygen for Elektra Projekt from the source
       code.