Provided by: elektra-doc_0.7.1-1_all 
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:
· kdbOpen()
· kdbClose()
· kdbGet()
· kdbSet()
The two essential functions for dynamic information about backends are:
· kdbGetMountpoint()
· kdbGetCapability()
They use some backend implementation to know the details about how to access the storage.
Currently we have this backends:
· berkeleydb: the keys are stored in a Berkeley DB database, providing very small
footprint, speed, and other advantages.
· filesys: the key hierarchy and data are saved as plain text files in the filesystem.
· ini: the key hierarchy are saved into configuration files.
See also:
http://www.libelektra.org/Ini
· fstab: a reference backend used to interpret the /etc/fstab file as a set of keys under
system/filesystems .
· 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:
· You must relay completely on the backend-dependent methods.
· You may use or reimplement the second set of methods.
· You should completely reimplement in your language the higher lever methods.
· 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:
· 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.
· 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.
· 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.
· 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.
· 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.
· 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.
· 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.
· 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().
· 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():
· 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.
· option_t::KDB_O_SYNC
Will force to save all keys, independent of their sync state.
· 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.
· 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.