Main Page | Modules | Data Structures | File List | Data Fields

KeyDB :: Class Methods

General methods to access the Key database. More...

Data Structures

struct  _KDBInfo
 Object returned by kdbGetInfo() containing some informations about the Elektra library and backend being used. More...

Typedefs

typedef _KDBInfo KDBInfo
 Object returned by kdbGetInfo() containing some informations about the Elektra library and backend being used.

Enumerations

enum  KDBErr {
  KDB_RET_OK = 0,
  KDB_RET_NULLKEY = EINVAL,
  KDB_RET_UNINITIALIZED = EINVAL,
  KDB_RET_NOTFOUND = ENOENT,
  KDB_RET_INVALIDKEY = ESRCH,
  KDB_RET_NOKEY = ENXIO,
  KDB_RET_NODATA = ENODEV,
  KDB_RET_NODESC = ENOTDIR,
  KDB_RET_NODOMAIN = EDOM,
  KDB_RET_NOGROUP = ECHILD,
  KDB_RET_NOTIME = ENOTTY,
  KDB_RET_NOCRED = EACCES,
  KDB_RET_TRUNC = ERANGE,
  KDB_RET_NOMEM = ENOMEM,
  KDB_RET_TYPEMISMATCH = EBADF,
  KDB_RET_NOSYS = ENOSYS,
  KDB_RET_EBACKEND = EIO
}
 Some return codes generated by the Elektra library. More...
enum  KDBOptions {
  KDB_O_RECURSIVE = 1,
  KDB_O_DIR = 1<<1,
  KDB_O_DIRONLY = 1<<2 ,
  KDB_O_STATONLY = 1<<4,
  KDB_O_INACTIVE = 1<<5,
  KDB_O_SORT = 1<<6,
  KDB_O_NFOLLOWLINK = 1<<7,
  KDB_O_CONDENSED = 1<<8,
  KDB_O_NUMBERS = 1<<9,
  KDB_O_XMLHEADERS = 1<<10,
  KDB_O_FULLNAME = 1<<11,
  KDB_O_FULLUGID = 1<<12,
  KDB_O_HIER = 1<<13,
  KDB_O_NOCASE = 1<<15,
  KDB_O_NOSPANPARENT = 1<<16
}
 Options to change the default behavior of some methods. More...

Functions

int kdbOpen ()
 Opens the session with the Key database, using a backend defined by environment var $KDB_BACKEND.
int kdbOpenDefault ()
 Opens the session with the Key database.
int kdbOpenBackend (char *backendName)
 Opens the session with the Key database, dynamically loading a specific beckend for libelektra.so.
int kdbClose ()
 Closes the session with the Key database.
int kdbGetValue (const char *keyname, char *returned, size_t maxSize)
 A high-level method to get a key value, by key name.
int kdbSetValue (const char *keyname, const char *value)
 A high-level method to set a value to a key, by key name.
int kdbGetValueByParent (const char *parentName, const char *baseName, char *returned, size_t maxSize)
 Fills the returned buffer with the value of a key, which name is the concatenation of parentName and baseName.
int kdbSetValueByParent (const char *parentName, const char *baseName, const char *value)
 Sets the provided value to the key whose name is the concatenation of parentName and baseName.
int kdbGetKeyByParent (const char *parentName, const char *baseName, Key *returned)
 Given a parent key name plus a basename, returns the key.
int kdbGetKeyByParentKey (const Key *parent, const char *baseName, Key *returned)
 Similar to previous, provided for convenience.
ssize_t kdbGetKeyChildKeys (const Key *parentKey, KeySet *returned, unsigned long options)
 Retrieve a number of keys at once.
ssize_t kdbGetChildKeys (const char *parentName, KeySet *returned, unsigned long options)
 This method is similar and calls kdbGetKeyChildKeys().
ssize_t kdbGetRootKeys (KeySet *returned)
 Returns a KeySet with all root keys currently recognized and present on the system.
int kdbStatKey (Key *key)
 Taps the key only for its meta-info from the backend storage.
int kdbGetKey (Key *key)
 Fully retrieves the passed key from the backend storage.
int kdbSetKeys (KeySet *ks)
 Commits the ks KeySet to the backend storage, starting from ks's current position until its end.
int kdbSetKey (Key *key)
 Sets key in the backend storage.
int kdbRename (Key *key, const char *newName)
 Rename a key in the backend storage.
int kdbRemoveKey (const Key *key)
 Remove a key from the backend storage.
int kdbRemove (const char *keyName)
 Remove a key by its name from the backend storage.
int kdbLink (const char *oldPath, const char *newKeyName)
 Create a link key on the backend storage that points to other key.
uint32_t kdbMonitorKeys (KeySet *interests, uint32_t diffMask, unsigned long iterations, unsigned sleep)
 Monitor a KeySet for some key change.
uint32_t kdbMonitorKey (Key *interest, uint32_t diffMask, unsigned long iterations, unsigned sleep)
 Monitor a key change.
KDBInfo * kdbGetInfo (void)
 Returns a structure of information about the internals of the library and the backend used.
void kdbFreeInfo (KDBInfo *info)
 Frees the object returned by kdbGetInfo().
int kdbInfoToString (KDBInfo *info, char *string, size_t maxSize)
 Convenience method to provide a human readable text for what kdbGetInfo() returns.

Detailed Description

General methods to access the Key database.

To use them: 

#include <kdb.h>

This is the class that accesses the storage backend. When writing a new backend , these are the methods you'll have to reimplement: kdbOpen(), kdbClose(), kdbGetKey(), kdbSetKey(), kdbStatKey(), kdbGetKeyChildKeys(), kdbRemove(), kdbRename().

And methods that are suggested to reimplement (but not needed) if you want them to get the benefits of your new backend: kdbSetKeys(), kdbMonitorKey(), kdbMonitorKeys().

The other methods are higher level. They use the above methods to do their job, and generally don't have to be reimplemented for a different backend.

Language binding writers should follow the same rules:

Typedef Documentation

typedef struct _KDBInfo KDBInfo
 

Object returned by kdbGetInfo() containing some informations about the Elektra library and backend being used.

You should not allocate or deallocate memory for each of these members. This is a library responsability.

See also:
kdbGetInfo(), kdbFreeInfo(), kdbInfoToString()

commandInfo() of the 'kdb info' command to see it in action

Referenced by commandInfo(), kdbFreeInfo(), kdbGetInfo(), and kdbInfoToString().

Enumeration Type Documentation

enum KDBErr
 

Some return codes generated by the Elektra library.

These are Elektra specific errors only, that the library sets in errno. Other errors can be generated by system calls that the API uses. Then errno is propagated.

The idea is to keep compatibility to POSIX errno system, so each library error code maps to some POSIX E* error. Some mappings realy makes no sense, so to detect Elektra errors use the following error names, and to detect system's, use the naming convetions documented in errno man page.

A very robust program should check errno after each API call.

See also:
kdbGetChildKeys() for an example on how to handle errors
Enumeration values:
KDB_RET_OK  No error
KDB_RET_NULLKEY  Invalid Key object
KDB_RET_UNINITIALIZED  Object not initilized
KDB_RET_NOTFOUND  Key was not found
KDB_RET_INVALIDKEY  Key name is not 'system/something' or 'user/something...'
KDB_RET_NOKEY  Key has no name
KDB_RET_NODATA  Key has no data
KDB_RET_NODESC  Key has no comment/description
KDB_RET_NODOMAIN  Key has no user domain set
KDB_RET_NOGROUP  Key has no group
KDB_RET_NOTIME  Key has no access time set
KDB_RET_NOCRED  No credentials to access resource
KDB_RET_TRUNC  Buffer was too small
KDB_RET_NOMEM  Out of memory
KDB_RET_TYPEMISMATCH  Failed to convert key data due to data type
KDB_RET_NOSYS  Backend method not implemented
KDB_RET_EBACKEND  Error opening backend

Definition at line 219 of file kdb.h.

enum KDBOptions
 

Options to change the default behavior of some methods.

These options should be ORed.

See also:
kdbGetChildKeys()

ksToStream()

keyToStream()

Enumeration values:
KDB_O_RECURSIVE  Act recursively.
KDB_O_DIR  Include dir keys in result.
KDB_O_DIRONLY  Retrieve only directory keys.
KDB_O_STATONLY  Only stat key, instead of getting entirelly.
KDB_O_INACTIVE  Do not ignore inactive keys (that name begins with .).
KDB_O_SORT  Sort keys.
KDB_O_NFOLLOWLINK  Do not follow symlinks.
KDB_O_CONDENSED  Compressed XML, not usefull for human eyes.
KDB_O_NUMBERS  Use numbers intead of user and group names.
KDB_O_XMLHEADERS  Show also the XML header of the document.
KDB_O_FULLNAME  Export user keys using full name (e.g. user:username/some/key).
KDB_O_FULLUGID  Don't supress obvious key UID, GID, and user domain. Affects only user keys.
KDB_O_HIER  Export to the new hierarchical XML representation using key basename. See ksToStream().
KDB_O_NOCASE  Ignore case in ksLookup*() methods
KDB_O_NOSPANPARENT  Don't continue search if end of current folder reached, in ksLookupRE()

Definition at line 263 of file kdb.h.

Function Documentation

int kdbOpen (   ) 
 

Opens the session with the Key database, using a backend defined by environment var $KDB_BACKEND.

If the environment is not set the default backend will be opened.

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.

This is the best way to have affairs with the key database, unless the program is concerned about security and authentication (e.g. su, login, telnetd, etc), in which kdbOpenDefault() should be used. kdbOpen() is used by the kdb command.

Currently you can have only one backend (and key database session) initialized at a certain time.

To simply manipulate Key or KeySet objects without having to retrieve them from the storage, you don't need to open the key database before with any of the kdbOpen*() methods.

See also:
kdbOpenBackend(), kdbOpenDefault(), kdbClose()
Returns:
0 on success

-1 on failure is not set on failure up to now, because there is no backend using kdbOpen.

Definition at line 160 of file libkdb.c.

References kdbOpenBackend().

Referenced by commandExport(), and main().

int kdbOpenDefault (   ) 
 

Opens the session with the Key database.

Different from kdbOpen(), kdbOpenDefault() will completely ignore the $KDB_BACKEND environment and open the default backend. So kdbOpenDefault() must be used by programs concerned about security (e.g. su, login, sshd, etc).

The default backend use to be a symlink to the real backend, and is found in /lib/libelektra-default.so

See also:
kdbOpen(), kdbOpenBackend(), kdbClose()
Returns:
0 on success

-1 on failure is not set on failure up to now, because there is no backend using kdbOpen.

Definition at line 188 of file libkdb.c.

References kdbOpenBackend().

int kdbOpenBackend (  char *  backendName  ) 
 

Opens the session with the Key database, dynamically loading a specific beckend for libelektra.so.

After dynamic loading, the backend will be initialized with its implementation of kdbOpen().

Parameters:
backendName used to define the module filename as libelektra-"backendName".so
Returns:
0 on success.

-1 on failure is set to KDBErr::KDB_RET_NOSYS if backend library could not be opened KDBErr::KDB_RET_NOBACKEND if backend doesn't have the essential "kdbBackendFactory" initialization symbol KDBErr::KDB_RET_NOEXPORTS if backend failed to export its methods KDBErr::KDB_RET_NOKDBOPEN if backend does not provide a kdbOpen() implementation

See also:
kdbOpen()
Example of copying keys from one backend to another
KeySet *ks=ksNew();

kdbOpen(); // open default backend
kdbGetChildKeys("system/sw/httpd",ks, 
    KDB_O_NFOLLOWLINK |  // we want real links, not their targets
    KDB_O_INACTIVE |     // even commented (inactive) keys
    KDB_O_DIR |          // even pure directory keys
    KDB_O_RECURSIVE |    // all of this recursivelly
    KDB_O_SORT);         // sort all
kdbClose();

kdbOpenBackend("apache");

// The hipotethical libelektra-apache.so backend implementation for kdbSetKeys()
// simply interprets the passed KeySet and generates an old style
// equivalent /etc/httpd/httpd.conf file.
kdbSetKeys(ks);
kdbClose();

ksDel(ks);
Emulating same bahavior of previous example but now with the kdb command
bash# kdb export system/sw/httpd > apacheconf.xml
bash# KDB_BACKEND=apache kdb import apacheconf.xml

Definition at line 244 of file libkdb.c.

Referenced by kdbOpen(), and kdbOpenDefault().

int kdbClose (   ) 
 

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 after kdbClose().

This is the counterpart of kdbOpen().

See also:
kdbOpen()
Returns:
0 on success, anything else on failure, and errno is set. If the backend implementation of kdbOpen can't be found, errno is set to KDBErr::KDB_RET_NOSYS.

Definition at line 311 of file libkdb.c.

Referenced by commandExport().

int kdbGetValue (  const char *  keyname,
char *  returned,
size_t  maxSize
) 
 

A high-level method to get a key value, by key name.

This method is valid only for string keys. You should use other methods to get non-string keys.

Parameters:
keyname the name of the key to receive the value
returned a buffer to put the key value
maxSize the size of the buffer
Returns:
0 on success, or other value in case of error, and errno is set
See also:
kdbSetValue(), kdbGetKey(), kdbGetValueByParent(), keyGetString()

Definition at line 550 of file libkdb.c.

References kdbGetKey(), KEY_SWITCH_END, keyDel(), keyGetString(), and keyNew().

Referenced by kdbGetValueByParent().

int kdbSetValue (  const char *  keyname,
const char *  value
) 
 

A high-level method to set a value to a key, by key name.

It will obviously check if key exists first, and keep its metadata. So you'll not loose the precious key comment.

This will set a text key. So if the key was previously a binary, etc key, it will be retyped as text.

Parameters:
keyname the name of the key to receive the value
value the value to be set
Returns:
0 on success, other value otherwise, and errno is set
See also:
kdbGetValue(), keySetString(), kdbSetKey()

Definition at line 578 of file libkdb.c.

References kdbGetKey(), kdbSetKey(), KEY_SWITCH_END, keyDel(), keyNew(), and keySetString().

Referenced by kdbSetValueByParent().

int kdbGetValueByParent (  const char *  parentName,
const char *  baseName,
char *  returned,
size_t  maxSize
) 
 

Fills the returned buffer with the value of a key, which name is the concatenation of parentName and baseName.

Example:
char *parent="user/sw/MyApp";
char *keys[]={"key1","key2","key3"};
char buffer[150];   // a big buffer
int c;

for (c=0; c<3; c++) {
    kdbGetValueByParent(parent,keys[c],buffer,sizeof(buffer));
    // Do something with buffer....
}
Parameters:
parentName the name of the parent key
baseName the name of the child key
returned pre-allocated buffer to be filled with key value
maxSize size of the returned buffer
Returns:
whathever is returned by kdbGetValue()
See also:
kdbGetKeyByParent()

Definition at line 619 of file libkdb.c.

References kdbGetValue(), and strblen().

int kdbSetValueByParent (  const char *  parentName,
const char *  baseName,
const char *  value
) 
 

Sets the provided value to the key whose name is the concatenation of parentName and baseName.

Parameters:
parentName the name of the parent key
baseName the name of the child key
value the value to set whatever is returned by kdbSetValue()

Definition at line 642 of file libkdb.c.

References kdbSetValue(), and strblen().

int kdbGetKeyByParent (  const char *  parentName,
const char *  baseName,
Key *  returned
) 
 

Given a parent key name plus a basename, returns the key.

So here you'll provide something like

  • system/sw/myApp plus key1 to get system/sw/myApp/key1
  • user/sw/MyApp plus dir1/key2 to get user/sw/MyApp/dir1/key2

Parameters:
parentName parent key name
baseName leaf or child name
returned a pointer to an initialized key to be filled
Returns:
0 on success, or what kdbGetKey() returns, and errno is set
See also:
kdbGetKey(), kdbGetValueByParent(), kdbGetKeyByParentKey()

Definition at line 669 of file libkdb.c.

References kdbGetKey(), keySetName(), and strblen().

int kdbGetKeyByParentKey (  const Key *  parent,
const char *  basename,
Key *  returned
) 
 

Similar to previous, provided for convenience.

Parameters:
parent pointer to the parent key
See also:
kdbGetKey(), kdbGetKeyByParent(), kdbGetValueByParent()
Returns:
0 on success, or what kdbGetKey() returns, and errno is set

Definition at line 687 of file libkdb.c.

References kdbGetKey(), keyGetFullName(), keyGetFullNameSize(), keySetName(), and strblen().

ssize_t kdbGetKeyChildKeys (  const Key *  parentKey,
KeySet *  returned,
unsigned long  options
) 
 

Retrieve a number of keys at once.

This is one of the most practical methods of the library. And because of storing the keys in the efficient afterward, its very recommended to use it.

The existing KeySet (you must initializise it with ) will have all retrieved keys appended afterwards.

In default behaviour it will fully retrieve all keys in the specified directory, but not folder and inactive keys. The output is in a backend specific order.

Option can be any of the following:

  • KDBOptions::KDB_O_RECURSIVE
    Retrieve also the keys inside the folder keys inside the specified directory, recursively.
  • KDBOptions::KDB_O_DIR
    Include folders in the returned KeySet.
  • KDBOptions::KDB_O_DIRONLY
    Include in returned only the directory keys. The resulting KeySet will be only the skeleton of the tree. This option must be set together with KDB_O_DIR.
  • KDBOptions::KDB_O_STATONLY
    Only stat the keys. That means that it is free to the backend to retrieve the value, comment and key data type. The resulting keys may be empty and are only useful for meta info data requests. uses this option.
  • KDBOptions::KDB_O_INACTIVE
    Will make it not ignore inactive keys. So returned will be filled also with inactive keys. See elektra(7) to understand how inactive keys work.
  • KDBOptions::KDB_O_SORT
    Will sort keys alphabetically by their names.

Example:
char errormsg[300];
KeySet *myConfig;
Key *key;

key=keyNew("system/sw/MyApp",KEY_SWITCH_END);
myConfig=ksNew();

kdbOpen();
rc=kdbGetKeyChildKeys(key, myConfig, KDB_O_RECURSIVE);
keyDel(key); // free this resource.... we'll use it later
kdbClose();

// Check and handle propagated error
if (rc) switch (errno) {
    case KDB_RET_INVALIDKEY:
        sprintf(errormsg,"Something invalid");
        perror(errormsg); // use system error messages
        break;
    case KDB_RET_NOTFOUND:
        fprintf(stderr,"Key not found"); // custom error message
        break;
    default:
        sprintf(errormsg,"My application");
        perror(errormsg); // use system error messages
        break;
}

ksRewind(myConfig); // go to begining of KeySet
key=ksNext(myConfig);
while (key) {
    // do something with each key . . .

    key=ksNext(myConfig); // next key
}
Parameters:
parentKey parent key
returned the (pre-initialized) KeySet returned with all keys found
options ORed options to control approaches
See also:
KDBOptions

kdbGetChildKeys() for a convenience method

ksLookupByName(), ksLookupRE(), ksLookupByValue() for powerfull lookups after the KeySet was retrieved

ksSort() for what is done when you ask for KDBOptions::KDB_O_SORT

commandList() code in kdb command for usage example

commandEdit() code in kdb command for usage example

commandExport() code in kdb command for usage example

Returns:
number of keys contained by returned, or a negative value on error and errno is set

Definition at line 793 of file libkdb.c.

Referenced by commandList(), and kdbGetChildKeys().

ssize_t kdbGetChildKeys (  const char *  parentName,
KeySet *  returned,
unsigned long  options
) 
 

This method is similar and calls kdbGetKeyChildKeys().

It is provided for convenience.

Definition at line 810 of file libkdb.c.

References kdbGetKeyChildKeys(), KEY_SWITCH_END, keyDel(), and keyNew().

Referenced by commandEdit(), and commandList().

ssize_t kdbGetRootKeys (  KeySet *  returned  ) 
 

Returns a KeySet with all root keys currently recognized and present on the system.

Currently, the system and current user's user keys are returned.

Parameters:
returned the initialized KeySet to be filled
Returns:
the number of root keys found
See also:
KeyNamespace

commandList() code in kdb command for usage example

Definition at line 835 of file libkdb.c.

References _Key::flags, KEY_SWITCH_END, KEY_SWITCH_NEEDSYNC, keyDel(), keyNew(), ksInsert(), and _KeySet::size.

Referenced by commandList().

int kdbStatKey (  Key *  key  ) 
 

Taps the key only for its meta-info from the backend storage.

The bahavior may change from backend to backend. In the filesystem backend, it will make only a stat(2) on the key.

A key of type KEY_TYPE_LINK will have its target address loaded in the key structure, which can be accessed later using keyStealValue() or keyGetString(). This is the only way to know the target of a link key without dereferencing it (in contrast to kdbGetKey(), where the link is dereferenced).

Info like comments and key data type are not retrieved.

Parameters:
key an initialized Key pointer to be filled.
Returns:
0 on success, -1 otherwise

Definition at line 873 of file libkdb.c.

Referenced by commandList().

int kdbGetKey (  Key *  key  ) 
 

Fully retrieves the passed key from the backend storage.

Parameters:
key a pointer to a Key that has a name set
Returns:
0 on success, or other value and errno is set
See also:
kdbSetKey()

commandGet() code in kdb command for usage example

Definition at line 897 of file libkdb.c.

Referenced by commandEdit(), commandGet(), commandList(), commandSet(), kdbGetKeyByParent(), kdbGetKeyByParentKey(), kdbGetValue(), kdbMonitorKey_default(), kdbSetValue(), and keyNew().

int kdbSetKeys (  KeySet *  ks  ) 
 

Commits the ks KeySet to the backend storage, starting from ks's current position until its end.

This is why it is suggested that you call ksRewind() on ks beffore calling this method. Each key is checked with keyNeedsSync() before being actually commited. So only changed keys are updated.

If some error occurs, kdbSetKeys() stops and returns whatever kdbSetKey() returned. The KeySet internal cursor is left on the key that generated the error (so you may check it latter with ksCurrent()). The internal kdbSetKey() also sets errno in case of error.

Parameters:
ks a KeySet full of changed keys
Returns:
0 on success, or whatever kdbSetKey() returns
See also:
kdbSetKey(), keyNeedsSync(), ksNext(), ksCurrent()

commandEdit(), commandImport() code in kdb command for usage and error handling example

Definition at line 931 of file libkdb.c.

References kdbSetKeys_default().

Referenced by commandEdit(), and commandImport().

int kdbSetKey (  Key *  key  ) 
 

Sets key in the backend storage.

See also:
kdbGetKey(), kdbSetKeys()

commandSet() code in kdb command for usage example

Returns:
0 on success, or other value and errno is set

Definition at line 987 of file libkdb.c.

Referenced by commandSet(), kdbLink(), kdbSetKeys_default(), and kdbSetValue().

int kdbRename (  Key *  key,
const char *  newName
) 
 

Rename a key in the backend storage.

Parameters:
key the key to be renamed
newName the new key name
Returns:
0 on success, or whathever is returned by the backend implementation on failure, and errno is propagated

Definition at line 1012 of file libkdb.c.

Referenced by commandMove().

int kdbRemoveKey (  const Key *  key  ) 
 

Remove a key from the backend storage.

The key object will not be freed. It is your responsability to keyDel() it after kdbRemoveKey().

This method is not recursive.

Parameters:
key the key to be removed
Returns:
0 on success, or whathever is returned by the backend implementation on failure, and errno is propagated
See also:
commandRemove(), and ksCompare() code in kdb command for usage example

Definition at line 1040 of file libkdb.c.

Referenced by kdbRemove().

int kdbRemove (  const char *  keyName  ) 
 

Remove a key by its name from the backend storage.

This is a convenience to kdbRemoveKey().

Parameters:
keyName the name of the key to be removed
Returns:
0 on success, or whathever is returned by kdbRemoveKey(), and errno is propagated
See also:
commandRemove() code in kdb command for usage example

Definition at line 1065 of file libkdb.c.

References kdbRemoveKey(), KEY_SWITCH_END, keyDel(), keyNew(), and keySetName().

Referenced by commandEdit(), and commandRemove().

int kdbLink (  const char *  oldPath,
const char *  newKeyName
) 
 

Create a link key on the backend storage that points to other key.

Parameters:
oldPath destination key name
newKeyName name of the key that will be created and will point to
oldPath 
Returns:
whathever is returned by kdbSetKey(), and errno is set
See also:
commandLink() code in kdb command for usage example

commandSet() code in kdb command for usage example

Definition at line 1097 of file libkdb.c.

References kdbSetKey(), KEY_SWITCH_END, keyDel(), keyNew(), and keySetLink().

Referenced by commandLink().

uint32_t kdbMonitorKeys (  KeySet *  interests,
uint32_t  diffMask,
unsigned long  iterations,
unsigned  sleep
) 
 

Monitor a KeySet for some key change.

This method will scan the interests KeySet, starting and finishing in the KeySet's next cursor position, in a circular behavior, looking for some change defined in the diffMask mask. It will use kdbMonitorKey() and will return at the first key change ocurrence, or when requested iterations finish.

You may check the return code to see if some key changed, and get the updated key using ksCurrent().

Example:
KeySet *myConfigs;

myConfigs=ksNew();
kdbGetChildKeys("system/sw/MyApp",myConfigs,KDB_O_RECURSIVE | KDB_O_SORT);

// use the keys . . . .

// now monitor any key change
ksRewind(myConfigs);
while (1) {
    Key *changed=0;
    char keyName[300];
    char keyData[300];
    uint32_t diff;

    // block until any change in key value or comment . . .
    diff=kdbMonitorKeys(myConfigs,
        KEY_SWITCH_VALUE | KEY_SWITCH_COMMENT,
        0,0); // ad-infinitum

    changed=ksCurrent(myConfigs);
    keyGetName(changed,keyName,sizeof(keyName));

    switch (diff) {
        case KEY_SWITCH_FLAG:
            printf("Key %s was deleted\n",keyName);
            break;
        case KEY_SWITCH_NEEDSYNC:
            printf("No cretentials to access Key %s\n",keyName);
            break;
        default:
            keyGetString(changed,keyData,sizeof(keyData));
            printf("Key %s has changed its value to %s\n",keyName,keyData);
    }
}

ksDel(myConfigs);
See also:
kdbMonitorKey(), ksCurrent(), ksRewind(), ksNext(), KeySwitch

commandMonitor() code in kdb command for usage example

Definition at line 1171 of file libkdb.c.

References kdbMonitorKeys_default().

uint32_t kdbMonitorKey (  Key *  interest,
uint32_t  diffMask,
unsigned long  iterations,
unsigned  sleep
) 
 

Monitor a key change.

This method will block execution until one of the folowing happens:

  • All requested iterations, with requested sleep times, finish. If no change happens, zero is returned.
  • Requested key info and meta-info (defined by diffMask) changes when keyCompare()ed with the original interest.

interest should be a full key with name, value, comments, permissions, etc, and all will be compared and then masked by diffMask.

If interest is a folder key, use KEY_SWITCH_TIME in diffMask to detect a time change, so you'll know something happened (key modification, creation, deletion) inside the folder.

If interest was not found, or deleted, the method will return immediatly a KEY_SWITCH_FLAG value.

If you don't have access rights to interest, the method will return immediatly a KEY_SWITCH_NEEDSYNC value.

If something from diffMask has changed in interest, it will be updated, so when method returns, you'll have an updated version of the key.

Parameters:
interest key that will be monitored
diffMask what particular info change we are interested
iterations how many times to test. 0 means infinitum or until some change happens
sleep time to sleep, in microseconds, between iterations. 0 defaults to 1 second.
Returns:
the ORed KEY_SWITCH_* flags of what changed
See also:
KeySwitch

keyCompare()

kdbMonitorKeys() to monitor KeySets, and for a code example

commandMonitor() code in kdb command for usage example

Definition at line 1269 of file libkdb.c.

References kdbMonitorKey_default().

Referenced by commandMonitor(), and kdbMonitorKeys_default().

KDBInfo* kdbGetInfo (  void   ) 
 

Returns a structure of information about the internals of the library and the backend used.

Currently, the returned object has the following members:

  • version: the version for the Elektra library
  • backendName: the name of the storage backend that is or will be used
  • backendIsOpen: whether the backend was already opened with kdbOpen()

After use, the returned object must be freed with a call to kdbFreeInfo().

Example:
KDBInfo *info=0;

info=kdbGetInfo();
printf("The library version I'm using is %s\n",info->version);

kdbFreeInfo(info);
Returns:
0 on sucess, -1 if info is NULL, -2 if incompatible app version
See also:
kdbInfoToString(), kdbFreeInfo(), commandInfo()

Definition at line 1513 of file libkdb.c.

References _KDBInfo::backendIsOpen, _KDBInfo::backendName, KDBInfo, and _KDBInfo::version.

Referenced by commandInfo().

void kdbFreeInfo (  KDBInfo *  info  ) 
 

Frees the object returned by kdbGetInfo().

This method is provided so the programmer doesn't need to learn about the storage internals of the KDBInfo structure.

Parameters:
info the structure returned by kdbGetInfo()
See also:
kdbGetInfo(), kdbInfoToString(), commandInfo()

Definition at line 1548 of file libkdb.c.

References KDBInfo.

int kdbInfoToString (  KDBInfo *  info,
char *  string,
size_t  maxSize
) 
 

Convenience method to provide a human readable text for what kdbGetInfo() returns.

It is your responsability to allocate and free the string buffer. Currently, 200 bytes is a good size for a buffer.

Example:
KDBInfo *info=0;
char buffer[200];

info=kdbGetInfo();
kdbInfoToString(info,buffer,sizeof(buffer));
printf("Follows some information about Elektra:\n");
printf(buffer);
printf("\n");

kdbFreeInfo(info);
Parameters:
info the object returned by kdbGetInfo()
string a pre-allocated buffer to fill with human readable information
maxSize the size of the string buffer, to avoid memory problems
Returns:
0 on success, -1 if info is NULL
See also:
kdbGetInfo(), kdbFreeInfo(), commandInfo()

Definition at line 1581 of file libkdb.c.

References _KDBInfo::backendIsOpen, _KDBInfo::backendName, KDBInfo, and _KDBInfo::version.

Referenced by commandInfo().

Generated on Sun Feb 19 10:05:37 2006 for Elektra Project by  doxygen 1.3.9.1