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...

Enumerations

enum  KDBErr {
  KDB_RET_OK = 0,
  KDB_RET_NULLKEY = EINVAL,
  KDB_RET_UNINITIALIZED = EINVAL,
  KDB_RET_NOTFOUND = ENOENT,
  KDB_RET_INVALIDKEY = 1001,
  KDB_RET_NOKEY = 1002,
  KDB_RET_NODATA = 1003,
  KDB_RET_NODESC = 1004,
  KDB_RET_NODOMAIN = 1005,
  KDB_RET_NOGROUP = 1006,
  KDB_RET_NOTIME = 1007,
  KDB_RET_NOCRED = EACCES,
  KDB_RET_TRUNC = ERANGE,
  KDB_RET_NOMEM = ENOMEM,
  KDB_RET_TYPEMISMATCH = 1008,
  KDB_RET_NOSYS = ENOSYS,
  KDB_RET_EBACKEND = 1009
}
 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,
  KDB_O_ALL = 1<<17
}
 Options to change the default behavior of some methods. More...

Functions

int kdbOpen (KDBHandle *handle)
 Opens the session with the Key database, using a backend defined by environment var $KDB_BACKEND.
int kdbOpenDefault (KDBHandle *handle)
 Opens the session with the Key database.
int kdbOpenBackend (KDBHandle *handle, char *backendName)
 Opens the session with the Key database, dynamically loading a specific beckend for libelektra.so.
int kdbClose (KDBHandle *handle)
 Closes the session with the Key database.
ssize_t kdbGetKeyChildKeys (KDBHandle handle, const Key *parentKey, KeySet *returned, unsigned long options)
 Retrieve a number of inter-related keys at once.
int kdbStatKey (KDBHandle handle, Key *key)
 Stats the key only for its meta-info from the backend storage.
int kdbGetKey (KDBHandle handle, Key *key)
 Fully retrieves the passed key from the backend storage.
int kdbSetKeys (KDBHandle handle, KeySet *ks)
 Commits the ks KeySet to the backend storage, starting from ks's current position until its end.
int kdbSetKey (KDBHandle handle, Key *key)
 Sets key in the backend storage.
int kdbRename (KDBHandle handle, Key *key, const char *newName)
 Rename a key in the backend storage.
int kdbRemoveKey (KDBHandle handle, const Key *key)
 Remove a key from the backend storage.
int kdbLink (KDBHandle handle, const char *oldPath, const char *newKeyName)
 Create a link key on the backend storage that points to other key.
uint32_t kdbMonitorKeys (KDBHandle handle, KeySet *interests, uint32_t diffMask, unsigned long iterations, unsigned sleep)
 Monitor a KeySet for some key change.
uint32_t kdbMonitorKey (KDBHandle handle, Key *interest, uint32_t diffMask, unsigned long iterations, unsigned sleep)
 Monitor a key change.
KDBInfokdbGetInfo (KDBHandle handle)
 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.
char * kdbStrError (int errnum)
 Provides an error string associated with errnum.
int kdbPrintError (const char *msg)
 Prints an error message related to errno on standard error, prefixed by msg.

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 .

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

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

In general usage, the default backend will be used, which is a pointer to some other backend. Your program can use a different backend simply by setting the KDB_BACKEND environment variable. Or, if you know what you are doing, you can hardcode it in your code and use the explicit kdbOpenBackend() method to use one. These options should really not used, thus you destroy the global namespace with that.

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

Language binding writers should follow the same rules:


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
Enumerator:
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 230 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()

Enumerator:
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()
KDB_O_ALL  Restart search, in ksLookup*() from start -> cursor when cursor -> end failed

Definition at line 274 of file kdb.h.


Function Documentation

int kdbOpen ( KDBHandle *  handle  ) 

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.

The handle parameter will be initialized with an environment, and it should be passed along on any kdb*() method your application calls.

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

Parameters:
handle the key database handler to initialize
See also:
kdbOpenBackend(), kdbOpenDefault(), kdbClose()
Returns:
0 on success

-1 on failure and errno is propagated from kdbOpenBackend() using kdbOpen.

Definition at line 200 of file libelektra/kdb.c.

References kdbOpenBackend().

Referenced by commandExport().

int kdbOpenDefault ( KDBHandle *  handle  ) 

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

The handle parameter will be initialized with an environment, and it should be passed along on any kdb*() method your application calls.

Parameters:
handle the key database handler to initialize
See also:
kdbOpen(), kdbOpenBackend(), kdbClose()
Returns:
0 on success

-1 on failure and is set using kdbOpen.

Definition at line 231 of file libelektra/kdb.c.

References kdbOpenBackend().

int kdbOpenBackend ( KDBHandle *  handle,
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().

The handle parameter will be initialized with an environment, and it should be passed along on any kdb*() method your application calls.

Parameters:
handle the key database handler to initialize
backendName used to define the module filename as libelektra-"backendName".so
Returns:
0 on success.

-1 on failure and errno is set to

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

kdbOpen(&handle); // open default backend
kdbGetChildKeys(handle,"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(&handle);

kdbOpenBackend(&handle,"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(handle,ks);
kdbClose(&handle);

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 291 of file libelektra/kdb.c.

References KDB_RET_EBACKEND, KDB_RET_NOSYS, kdbBackendFactory(), and kdbhSetUserName().

Referenced by kdbOpen(), and kdbOpenDefault().

int kdbClose ( KDBHandle *  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().

Parameters:
handle the key database handler to initialize
See also:
kdbOpen()
Returns:
0 on success

-1 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 379 of file libelektra/kdb.c.

References KDB_RET_NOSYS.

Referenced by commandExport().

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

Retrieve a number of inter-related keys at once.

This is one of the most practical methods of the library, and you should use it to retrieve in one shot all keys needed by your application.

The returned KeySet must be initialized or may already contain some keys (in this case, the new retrieved keys will be simply appended).

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

The parent key per se will not be retrieved. This is the job of the caller.

The option is an array of the following ORed flags:

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

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

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

// Check and handle propagated error
if (rc) switch (errno) {
    case KDB_RET_INVALIDKEY:
        sprintf(errormsg,"Something invalid");
        kdbPrintError(errormsg);
        break;
    case KDB_RET_NOTFOUND:
        fprintf(stderr,"Key not found"); // custom error message
        break;
    default:
        sprintf(errormsg,"My application");
        kdbPrintError(errormsg);
        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, KDBErr

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 KeyDB :: Class Methods command for usage example

commandEdit() code in KeyDB :: Class Methods command for usage example

commandExport() code in KeyDB :: Class Methods command for usage example

Returns:
number of keys contained by returned or -1 on failure, errno is propagated and can be KDBErr::KDB_RET_INVALIDKEY, KDBErr::KDB_RET_NOTFOUND, KDBErr::KDB_RET_NOSYS

Definition at line 496 of file libelektra/kdb.c.

References KDB_RET_NOSYS.

Referenced by commandList(), and kdbGetChildKeys().

int kdbStatKey ( KDBHandle  handle,
Key key 
)

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

The key may not hold value and comment after using kdbStatKey().

A key of type KeyType::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 followed).

Info like comments and key data type may not be retrieved if backend supports a way not to get them.

Parameters:
key an initialized Key pointer to be filled.
Returns:
0 on success

-1 on failure and errno is propagated

Definition at line 527 of file libelektra/kdb.c.

References KDB_RET_NOSYS.

Referenced by commandList().

int kdbGetKey ( KDBHandle  handle,
Key key 
)

Fully retrieves the passed key from the backend storage.

The backend will try to get the key, identified through its name.

Parameters:
key a pointer to a Key that has a name set
Returns:
0 on success

-1 on failure and errno is propagated

See also:
commandGet() code in KeyDB :: Class Methods command for usage example

Definition at line 554 of file libelektra/kdb.c.

References KDB_RET_NOSYS.

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

int kdbSetKeys ( KDBHandle  handle,
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 before calling this method.

Each key is checked with keyNeedsSync() before being actually commited. So only changed keys are updated.

If some error occurs, kdbSetKeys() will stop. In this situation the KeySet internal cursor is left on the key that generated the error.

Example of how this method must be used:
KeySet *ks;  // the KeySet I want to set

// ommited... fill ks with some keys

ksRewind(ks);
while ((ret=kdbSetKeys(handle,ks))) {
    // We got an error. Warn user.
    Key *problem;
    char error[500]="";
    char keyname[300]="";

    problem=ksCurrent(ks);
    if (problem) keyGetFullName(problem,keyname,sizeof(keyname));
    sprintf(error,"kdb import: while importing %s", keyname);
    kdbPrintError(error);

    // And try to set keys again starting from the next key,
    // unless we reached the end of KeySet
    if (ksNext(ks) == 0) break;
}
Parameters:
ks a KeySet full of changed keys
Returns:
0 on success

-1 on failure and errno is propagated

See also:
kdbSetKey(), keyNeedsSync(), ksNext(), ksCurrent()

commandEdit(), commandImport() code in KeyDB :: Class Methods command for usage and error handling example

Definition at line 611 of file libelektra/kdb.c.

References KDB_RET_NOSYS, and kdbSetKeys_default().

Referenced by commandEdit(), and commandImport().

int kdbSetKey ( KDBHandle  handle,
Key key 
)

Sets key in the backend storage.

Directory keys will be created recursivelly if needed. In case a path component is found in the storage as a regular non-dir key, it will be converted into a dir key if possible.

See also:
kdbGetKey(), kdbSetKeys()

commandSet() code in KeyDB :: Class Methods command for usage example

Returns:
0 on success

-1 on failure and errno is propagated

Definition at line 644 of file libelektra/kdb.c.

References KDB_RET_NOSYS.

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

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

Rename a key in the backend storage.

key must be a fully retrieved key. If you want another name its not enough to kdbSetKey() it again (old key would stay, you could remove it with kdbRemoveKey though).

kdbRename() can do it for you, maybe with a more efficient method then described above.

Parameters:
key the key to be renamed
newName the new key name
Returns:
0 on success

-1 on failure and errno is propagated

Definition at line 676 of file libelektra/kdb.c.

References KDB_RET_NOSYS, and kdbRename_default().

Referenced by commandMove().

int kdbRemoveKey ( KDBHandle  handle,
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

-1 on failure and errno is propagated

See also:
commandRemove(), and ksCompare() code in KeyDB :: Class Methods command for usage example

Definition at line 709 of file libelektra/kdb.c.

References KDB_RET_NOSYS.

Referenced by kdbRemove().

int kdbLink ( KDBHandle  handle,
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 KeyDB :: Class Methods command for usage example

commandSet() code in KeyDB :: Class Methods command for usage example

Definition at line 736 of file libelektra/kdb.c.

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

Referenced by commandLink().

uint32_t kdbMonitorKeys ( KDBHandle  handle,
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;

// key db initialization omitted

myConfigs=ksNew();
kdbGetChildKeys(handle,"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(handle,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 KeyDB :: Class Methods command for usage example

Returns:
diff mask on success

-1 on failure and errno is propagated

Definition at line 814 of file libelektra/kdb.c.

References KDB_RET_NOSYS, and kdbMonitorKeys_default().

uint32_t kdbMonitorKey ( KDBHandle  handle,
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:

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

0 on success

-1 on failure and errno is propagated

See also:
KeySwitch

keyCompare()

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

commandMonitor() code in KeyDB :: Class Methods command for usage example

Definition at line 918 of file libelektra/kdb.c.

References KDB_RET_NOSYS, and kdbMonitorKey_default().

Referenced by commandMonitor(), and kdbMonitorKeys_default().

KDBInfo* kdbGetInfo ( KDBHandle  handle  ) 

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

Currently, the returned object has the following members:

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

Example:
KDBInfo *info=0;

// key dababase initialization omitted

info=kdbGetInfo(handle);
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 968 of file libelektra/kdb.c.

References _KDBInfo::backendIsOpen, _KDBInfo::backendName, 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 1003 of file libelektra/kdb.c.

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];

// key dababase initialization omitted

info=kdbGetInfo(handle);
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 1274 of file libelektra/kdb.c.

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

Referenced by commandInfo().

char* kdbStrError ( int  errnum  ) 

Provides an error string associated with errnum.

Returns:
an error string associated with errnum.
See also:
kdbPrintError()

Definition at line 38 of file error.c.

References KDB_RET_EBACKEND, KDB_RET_INVALIDKEY, KDB_RET_NODATA, KDB_RET_NODESC, KDB_RET_NODOMAIN, KDB_RET_NOGROUP, KDB_RET_NOKEY, KDB_RET_NOSYS, KDB_RET_NOTIME, and KDB_RET_TYPEMISMATCH.

Referenced by kdbPrintError().

int kdbPrintError ( const char *  msg  ) 

Prints an error message related to errno on standard error, prefixed by msg.

See also:
kdbStrError()

example on kdbGetKeyChildKeys()

Definition at line 71 of file error.c.

References kdbStrError().

Referenced by commandEdit(), commandGet(), commandImport(), commandLink(), commandList(), commandMove(), commandRemove(), and commandSet().


Generated on Mon Dec 17 18:45:35 2007 for Elektra Project by  doxygen 1.5.4