Main Page | Modules | File List

KeyDB Class Methods

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

Enumerations

enum  KDBErr {
  KDB_RET_OK = 0,
  KDB_RET_NULLKEY = EINVAL,
  KDB_RET_UNINITIALIZED = EINVAL,
  KDB_RET_NOKEY = ENOMSG,
  KDB_RET_NODATA = ENOMSG,
  KDB_RET_NOGROUP = ENOMSG,
  KDB_RET_NODESC = ENOMSG,
  KDB_RET_NODOMAIN = ENOMSG,
  KDB_RET_NOCRED = EACCES,
  KDB_RET_NOTIME = ENOMSG,
  KDB_RET_TRUNC = ENOBUFS,
  KDB_RET_TYPEMISMATCH = EILSEQ,
  KDB_RET_INVALIDKEY = EAFNOSUPPORT,
  KDB_RET_NOTFOUND = ENOENT
}
enum  KDBOptions {
  KDB_O_RECURSIVE = 1,
  KDB_O_DIR = 1<<1,
  KDB_O_NOVALUE = 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
}

Functions

int kdbOpen ()
int kdbClose ()
int kdbGetValue (const char *keyname, char *returned, size_t maxSize)
int kdbSetValue (const char *keyname, const char *value)
int kdbGetValueByParent (const char *parentName, const char *baseName, char *returned, size_t maxSize)
int kdbSetValueByParent (const char *parentName, const char *baseName, const char *value)
int kdbGetKeyByParent (const char *parentName, const char *baseName, Key *returned)
int kdbGetKeyByParentKey (const Key *parent, const char *baseName, Key *returned)
int kdbGetChildKeys (const char *parentName, KeySet *returned, unsigned long options)
int kdbGetRootKeys (KeySet *returned)
int kdbStatKey (Key *key)
int kdbGetKey (Key *key)
int kdbSetKeys (KeySet *ks)
int kdbSetKey (Key *key)
int kdbRemove (const char *keyName)
int kdbLink (const char *oldPath, const char *newKeyName)
u_int32_t kdbMonitorKeys (KeySet *interests, u_int32_t diffMask, unsigned long iterations, unsigned sleep)
u_int32_t kdbMonitorKey (Key *interest, u_int32_t diffMask, unsigned long iterations, unsigned sleep)

Variables

enum KDBOptions kdbOption

Detailed Description

General methods to access the Key database.

To use them: 

#include <kdb.h>

Enumeration Type Documentation

enum KDBErr
 

Some return codes generated by the Elektra library.

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

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

Enumeration values:
KDB_RET_OK  No error
KDB_RET_NULLKEY  Invalid Key object
KDB_RET_UNINITIALIZED  Object not initilized
KDB_RET_NOKEY  Key has no name
KDB_RET_NODATA  Key has no data
KDB_RET_NOGROUP  Key has no group
KDB_RET_NODESC  Key has no comment/description
KDB_RET_NODOMAIN  Key has no user domain set
KDB_RET_NOCRED  No credentials to access resource
KDB_RET_NOTIME  Key has no access time set
KDB_RET_TRUNC  Buffer was too small
KDB_RET_TYPEMISMATCH  Failed to convert key data due to data type
KDB_RET_INVALIDKEY  Key name is no 'system/' or 'user/'
KDB_RET_NOTFOUND  Key was not found

Definition at line 166 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_NOVALUE  Retrieve only keys that don't have values (a.k.a dir 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 UID and GID intead of user and group names
KDB_O_XMLHEADERS  Show also the XML header of the document

Definition at line 193 of file kdb.h.

Function Documentation

int kdbClose (   ) 
 

Closes a session with the Key database.

This is the counterpart of kdbOpen().

See also:
kdbOpen()

Definition at line 106 of file localkdb.c.

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

Retrieve a number of inter-related keys in one shot. This is one of the most practicall methods of the library. Returns a KeySet with all retrieved keys. So if your application keys live bellow system/sw/myApp, you'll use this method to get them all.

Option can be any of the following, ORed:

  • KDB_O_RECURSIVE
    Retrieve also the keys under the child keys, recursively. The kdb(1) ls command, with switch -R uses this option.
  • KDB_O_DIR
    By default, folder keys will not be returned because they don't have values and exist only to define hierarchy. Use this option if you need them to be included in the returned KeySet.
  • KDB_O_NOVALUE
    Do not include in returned the regular value keys. The resulting KeySet will be only the skeleton of the tree.
  • KDB_O_STATONLY
    Only stat(2) the keys; do not retrieve the value, comment and key data type. The resulting keys will be empty and usefull only for informational purposes. The kdb(1) ls command, without the -v switch uses this option.
  • KDB_O_INACTIVE
    Will make it not ignore inactive keys. So returned will be filled also with inactive keys. See registry(7) to understand how inactive keys work.
  • KDB_O_SORT
    Will sort keys alphabetically by their names.

Example:
KeySet myConfig;
ksInit(&myConfig);

kdbOpen();
rc=kdbGetChildKeys("system/sw/MyApp", &myConfig, KDB_O_RECURSIVE);
kdbClose();

// Check and handle propagated error
if (rc) switch (errno) {
    case....
    case...
}

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

    key=ksNext(&myConfig)); // next key
}
Parameters:
parentName name of the parent key
returned the KeySet returned with all keys found
options ORed options to control approaches
See also:
KDBOptions

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:
0 on success, other value on error and errno is set

Definition at line 1040 of file localkdb.c.

References KDB_O_DIR, KDB_O_INACTIVE, KDB_O_NFOLLOWLINK, KDB_O_NOVALUE, KDB_O_RECURSIVE, KDB_O_SORT, KDB_O_STATONLY, KDB_RET_NOCRED, kdbGetKey(), kdbStatKey(), keyClose(), keyGetFullName(), keyGetFullNameSize(), keyInit(), keyIsLink(), keySetName(), ksAppend(), ksAppendKeys(), and ksInit().

Referenced by commandEdit(), and 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 1258 of file localkdb.c.

References KEY_FLAG_NEEDSYNC, and keyIsDir().

Referenced by commandEdit(), commandGet(), commandList(), commandMonitor(), commandSet(), kdbGetChildKeys(), kdbGetKeyByParent(), kdbGetKeyByParentKey(), kdbGetRootKeys(), kdbGetValue(), kdbMonitorKey(), and kdbSetValue().

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 932 of file localkdb.c.

References kdbGetKey(), and keySetName().

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 951 of file localkdb.c.

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

int kdbGetRootKeys (  KeySet *  returned  ) 
 

Returns a KeySet with all root keys currently recognized. Currently, the system and current user's user keys are returned.

Parameters:
returned the initialized KeySet to be filled
Returns:
0
See also:
KeyNamespace

commandList() code in kdb command for usage example

Definition at line 1180 of file localkdb.c.

References kdbGetKey(), keyInit(), keySetName(), ksAppend(), and ksInsert().

Referenced by commandList().

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.

See also:
kdbSetValue()

kdbGetKey()

kdbGetValueByParent()

keyGetString()

Returns:
0 on success, or other value and errno is set
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

Definition at line 817 of file localkdb.c.

References kdbGetKey(), keyClose(), keyGetString(), keyInit(), and keySetName().

Referenced by kdbGetValueByParent().

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....
}
See also:
kdbGetKeyByParent()
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()

Definition at line 889 of file localkdb.c.

References kdbGetValue().

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

Create a link key 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 1491 of file localkdb.c.

References kdbSetKey(), keyClose(), keyInit(), and keySetName().

Referenced by commandLink().

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

Monitor a key change.

This method will block your program 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_FLAG_HASTIME 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_FLAG_FLAG value.

If you don't have access rights to interest, the method will return immediatly a KEY_FLAG_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, when 0 means until some change happens
sleep time to sleep, in microseconds, between iterations. 0 defaults to 1 second.
Returns:
the ORed KEY_FLAG_* flags of what changed
See also:
KeyFlags

keyCompare()

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

commandMonitor() code in kdb command for usage example

Definition at line 1639 of file localkdb.c.

References KDB_RET_NOCRED, KDB_RET_NOTFOUND, kdbGetKey(), KEY_FLAG_FLAG, KEY_FLAG_NEEDSYNC, keyClose(), keyCompare(), keyDup(), keyGetNameSize(), and keyInit().

Referenced by commandMonitor(), and kdbMonitorKeys().

u_int32_t kdbMonitorKeys (  KeySet *  interests,
u_int32_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 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;

ksInit(&myConfigs);
kdbGetChildKeys("system/sw/MyApp",&myConfigs,KDB_O_ALL);

// use the keys . . . .

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

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

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

    switch (diff) {
        case KEY_FLAG_FLAG:
            printf("Key %s was deleted\n",keyName);
            break;
        case KEY_FLAG_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);
    }
}
See also:
kdbMonitorKey()

ksCurrent()

ksRewind()

ksNext()

KeyFlags

commandMonitor() code in kdb command for usage example

Definition at line 1569 of file localkdb.c.

References kdbMonitorKey(), ksCurrent(), and ksNext().

int kdbOpen (   ) 
 

Opens a session with the Key database

By now it does nothing. This might change in the future, so it's good practice to always call kdbOpen() before using the Elektra database.

See also:
kdbClose()

Definition at line 95 of file localkdb.c.

int kdbRemove (  const char *  keyName  ) 
 

Remove a key from the backend storage. This method is not recursive.

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

Definition at line 1461 of file localkdb.c.

References keyClose(), keyInit(), and keySetName().

Referenced by commandEdit(), and commandRemove().

int kdbSetKey (  Key *  key  ) 
 

Commits a key to the backend storage. If failed (see return), the errno global is set accordingly.

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 1330 of file localkdb.c.

References KDB_RET_INVALIDKEY, KEY_FLAG_NEEDSYNC, keyClose(), keyGetAccess(), keyGetGID(), keyGetUID(), keyInit(), keyIsDir(), keyIsLink(), and keySetName().

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

int kdbSetKeys (  KeySet *  ks  ) 
 

Commits an entire KeySet to the backend storage. Each key is checked with keyNeedsSync() before being actually commited. So only changed keys are updated.

Parameters:
ks a KeySet full of changed keys
Returns:
0 (no way to know if some key failled currently)
See also:
kdbSetKey()

commandEdit() code in kdb command for usage example

commandLoad() code in kdb command for usage example

Definition at line 1306 of file localkdb.c.

References kdbSetKey(), and keyNeedsSync().

Referenced by commandEdit(), and commandImport().

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.

See also:
kdbGetValue()

keySetString()

kdbSetKey()

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

Definition at line 848 of file localkdb.c.

References kdbGetKey(), kdbSetKey(), keyClose(), keySetName(), and keySetString().

Referenced by kdbSetValueByParent().

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

Definition at line 907 of file localkdb.c.

References kdbSetValue().

int kdbStatKey (  Key *  key  ) 
 

Retrieves only the meta-info of a key from backend storage. The bahavior may change from backend to backend. In the filesystem backend, it will make only a stat to the key.

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 1218 of file localkdb.c.

References KEY_FLAG_NEEDSYNC, and keyIsLink().

Referenced by commandList(), and kdbGetChildKeys().

Variable Documentation

enum KDBOptions kdbOption
 

Options to change the default behavior of some methods.

These options should be ORed.

See also:
kdbGetChildKeys()

ksToStream()

keyToStream()

Generated on Tue Aug 31 08:40:43 2004 for Elektra Project by doxygen 1.3.6