General methods to access the Key database.
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)
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:
The two essential functions for dynamic information about backends are:
They use some backend implementation to know the details about how to access the storage. Currently we have this backends:
See also:
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 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:
Parameters:
Returns:
-1 on NULL pointer
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.
The option is an array of the following ORed flags:
Example:.RS 4
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.
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:
See also:
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:
-1 on failure
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 informations about mounted backends.
Example:.RS 4
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 %s,
keyValue(mountpoint),
keyName(mountpoint));
kdbClose (handle);
keyDel (key);
Parameters:
Returns:
Maps the mountpoint, defined through its name and value, into the global elektra hierachy. 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:
Returns:
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 commiting 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:
Returns:
NULL on failure
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:.RS 4
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;
}
}
There are some options changing the behaviour of kdbSet():
When you dont 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:
Returns:
-1 on failure
See also:
keyRemove(), keyNeedRemove()
commandEdit(), commandImport() code in KDB :: Low Level Methods command for usage and error handling example
Unmount a backend that was mounted with kdbMount() before.
Parameters:
Returns:
Generated automatically by Doxygen for Elektra Projekt from the source code.