.TH "kdb::KDB" 3elektra "Tue Aug 19 2014" "Version 0.8.7" "Elektra" \" -*- nroff -*- .ad l .nh .SH NAME kdb::KDB \- .PP Opens the session with the \fBKey\fP database\&. .SH SYNOPSIS .br .PP .PP \fC#include \fP .SS "Public Member Functions" .in +1c .ti -1c .RI "\fBKDB\fP ()" .br .RI "\fIOpens the session with the \fBKey\fP database\&. \fP" .ti -1c .RI "\fBKDB\fP (\fBKey\fP &errorKey)" .br .RI "\fIOpens the session with the \fBKey\fP database\&. \fP" .ti -1c .RI "\fB~KDB\fP () throw ()" .br .ti -1c .RI "void \fBopen\fP (\fBKey\fP &errorKey)" .br .RI "\fIOpens the session with the \fBKey\fP database\&. \fP" .ti -1c .RI "void \fBclose\fP (\fBKey\fP &errorKey) throw ()" .br .ti -1c .RI "int \fBget\fP (\fBKeySet\fP &returned, std::string const &keyname)" .br .RI "\fIRetrieve keys in an atomic and universal way, all other \fBkdbGet()\fP Functions rely on that one\&. \fP" .ti -1c .RI "int \fBget\fP (\fBKeySet\fP &returned, \fBKey\fP &parentKey)" .br .RI "\fIRetrieve keys in an atomic and universal way, all other \fBkdbGet()\fP Functions rely on that one\&. \fP" .ti -1c .RI "int \fBset\fP (\fBKeySet\fP &returned, std::string const &keyname)" .br .ti -1c .RI "int \fBset\fP (\fBKeySet\fP &returned, \fBKey\fP &parentKey)" .br .in -1c .SH "Detailed Description" .PP Opens the session with the \fBKey\fP database\&. Constructs a class \fBKDB\fP\&. .PP \fBExceptions:\fP .RS 4 \fIKDBException\fP if database could not be opened .RE .PP 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 \fC\fBKDB\fP\fP datastructure will be initialized\&. .PP 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 \fBkdbClose()\fP\&. You can use the atexit () handler for it\&. .PP The pointer to the \fC\fBKDB\fP\fP structure returned will be initialized like described above, and it must be passed along on any kdb*() method your application calls\&. .PP Get a \fC\fBKDB\fP\fP handle for every thread using elektra\&. Don't share the handle across threads, and also not the pointer accessing it: .PP .nf thread1 { KDB * h; h = kdbOpen(0); // fetch keys and work with them kdbClose(h, 0); } thread2 { KDB * h; h = kdbOpen(0); // fetch keys and work with them kdbClose(h, 0); } .fi .PP .PP You don't need to use the \fBkdbOpen()\fP if you only want to manipulate plain in-memory \fBKey\fP or \fBKeySet\fP objects without any affairs with the backend key database or when your application loads plugins directly\&. .PP \fBParameters:\fP .RS 4 \fIerrorKey\fP the key which holds errors and warnings which were issued must be given .RE .PP \fBSee also:\fP .RS 4 \fBkdbClose()\fP to end all affairs to the \fBKey\fP database\&. .RE .PP \fBReturns:\fP .RS 4 a \fBKDB\fP pointer on success .PP NULL on failure .RE .PP Access to the key database\&. .PP \fBInvariant:\fP .RS 4 the object holds an valid connection to the key database or is empty .RE .PP .SH "Constructor & Destructor Documentation" .PP .SS "kdb::KDB::KDB ()\fC [inline]\fP" .PP Opens the session with the \fBKey\fP database\&. Constructs a class \fBKDB\fP\&. .PP \fBExceptions:\fP .RS 4 \fIKDBException\fP if database could not be opened .RE .PP 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 \fC\fBKDB\fP\fP datastructure will be initialized\&. .PP 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 \fBkdbClose()\fP\&. You can use the atexit () handler for it\&. .PP The pointer to the \fC\fBKDB\fP\fP structure returned will be initialized like described above, and it must be passed along on any kdb*() method your application calls\&. .PP Get a \fC\fBKDB\fP\fP handle for every thread using elektra\&. Don't share the handle across threads, and also not the pointer accessing it: .PP .nf thread1 { KDB * h; h = kdbOpen(0); // fetch keys and work with them kdbClose(h, 0); } thread2 { KDB * h; h = kdbOpen(0); // fetch keys and work with them kdbClose(h, 0); } .fi .PP .PP You don't need to use the \fBkdbOpen()\fP if you only want to manipulate plain in-memory \fBKey\fP or \fBKeySet\fP objects without any affairs with the backend key database or when your application loads plugins directly\&. .PP \fBParameters:\fP .RS 4 \fIerrorKey\fP the key which holds errors and warnings which were issued must be given .RE .PP \fBSee also:\fP .RS 4 \fBkdbClose()\fP to end all affairs to the \fBKey\fP database\&. .RE .PP \fBReturns:\fP .RS 4 a \fBKDB\fP pointer on success .PP NULL on failure .RE .PP .SS "kdb::KDB::KDB (\fBKey\fP &errorKey)\fC [inline]\fP" .PP Opens the session with the \fBKey\fP database\&. Constructs a class \fBKDB\fP\&. .PP \fBParameters:\fP .RS 4 \fIerrorKey\fP is useful if you want to get the warnings in the successful case, when no exception is thrown\&. .RE .PP \fBExceptions:\fP .RS 4 \fIKDBException\fP if database could not be opened .RE .PP 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 \fC\fBKDB\fP\fP datastructure will be initialized\&. .PP 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 \fBkdbClose()\fP\&. You can use the atexit () handler for it\&. .PP The pointer to the \fC\fBKDB\fP\fP structure returned will be initialized like described above, and it must be passed along on any kdb*() method your application calls\&. .PP Get a \fC\fBKDB\fP\fP handle for every thread using elektra\&. Don't share the handle across threads, and also not the pointer accessing it: .PP .nf thread1 { KDB * h; h = kdbOpen(0); // fetch keys and work with them kdbClose(h, 0); } thread2 { KDB * h; h = kdbOpen(0); // fetch keys and work with them kdbClose(h, 0); } .fi .PP .PP You don't need to use the \fBkdbOpen()\fP if you only want to manipulate plain in-memory \fBKey\fP or \fBKeySet\fP objects without any affairs with the backend key database or when your application loads plugins directly\&. .PP \fBParameters:\fP .RS 4 \fIerrorKey\fP the key which holds errors and warnings which were issued must be given .RE .PP \fBSee also:\fP .RS 4 \fBkdbClose()\fP to end all affairs to the \fBKey\fP database\&. .RE .PP \fBReturns:\fP .RS 4 a \fBKDB\fP pointer on success .PP NULL on failure .RE .PP .SS "kdb::KDB::~KDB ()\fC [inline]\fP" .PP The destructor closes the database\&. .PP Closes the session with the \fBKey\fP database\&. .PP You should call this method when you finished your affairs with the key database\&. You can manipulate \fBKey\fP and \fBKeySet\fP objects also after \fBkdbClose()\fP\&. You must not use any kdb* call afterwards\&. You can implement \fBkdbClose()\fP in the atexit() handler\&. .PP This is the counterpart of \fBkdbOpen()\fP\&. .PP The \fChandle\fP parameter will be finalized and all resources associated to it will be freed\&. After a \fBkdbClose()\fP, this \fChandle\fP can't be used anymore, unless it gets initialized again with another call to \fBkdbOpen()\fP\&. .PP \fBSee also:\fP .RS 4 \fBkdbOpen()\fP .RE .PP \fBParameters:\fP .RS 4 \fIhandle\fP contains internal information of \fBopened \fP key database .br \fIerrorKey\fP the key which holds error information .RE .PP \fBReturns:\fP .RS 4 0 on success .PP -1 on NULL pointer .RE .PP .SH "Member Function Documentation" .PP .SS "void kdb::KDB::close (\fBKey\fP &errorKey)\fC [inline]\fP" .PP Open the database\&. .PP The return value does not matter because its only a null pointer check\&. .PP \fBParameters:\fP .RS 4 \fIerrorKey\fP is useful if you want to get the warnings .RE .PP Closes the session with the \fBKey\fP database\&. .PP You should call this method when you finished your affairs with the key database\&. You can manipulate \fBKey\fP and \fBKeySet\fP objects also after \fBkdbClose()\fP\&. You must not use any kdb* call afterwards\&. You can implement \fBkdbClose()\fP in the atexit() handler\&. .PP This is the counterpart of \fBkdbOpen()\fP\&. .PP The \fChandle\fP parameter will be finalized and all resources associated to it will be freed\&. After a \fBkdbClose()\fP, this \fChandle\fP can't be used anymore, unless it gets initialized again with another call to \fBkdbOpen()\fP\&. .PP \fBSee also:\fP .RS 4 \fBkdbOpen()\fP .RE .PP \fBParameters:\fP .RS 4 \fIhandle\fP contains internal information of \fBopened \fP key database .br \fIerrorKey\fP the key which holds error information .RE .PP \fBReturns:\fP .RS 4 0 on success .PP -1 on NULL pointer .RE .PP .SS "int kdb::KDB::get (\fBKeySet\fP &returned, std::string const &keyname)\fC [inline]\fP" .PP Retrieve keys in an atomic and universal way, all other \fBkdbGet()\fP Functions rely on that one\&. Get all keys below keyname inside returned\&. .PP The \fCreturned\fP \fBKeySet\fP must be initialized\&. The \fCreturned\fP \fBKeySet\fP may already contain some keys\&. The new retrieved keys will be appended using \fBksAppendKey()\fP\&. .PP It will fully retrieve all keys under the \fCparentKey\fP folder, with all subfolders and their children\&. .SH "Example" .PP This example demonstrates the typical usecase within an application without updating\&. .PP \fBExample:\fP .RS 4 .PP .nf KeySet *myConfig = ksNew(0); Key *key = keyNew("system/sw/MyApp",KEY_END); KDB *handle = kdbOpen(key); kdbGet(handle, myConfig, key); keySetName(key, "user/sw/MyApp"); kdbGet(handle, myConfig, key); // check for errors in key keyDel(key); 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, 0); // no more affairs with the key database\&. .fi .PP .RE .PP .SH "Details" .PP When no backend could be found (e\&.g\&. no backend mounted) the default backend will be used\&. .PP If you pass NULL on any parameter \fBkdbGet()\fP will fail immediately without doing anything\&. .PP When a backend fails \fBkdbGet()\fP will return -1 without any changes to one of the parameter\&. .SH "Updating" .PP In the first run of kdbGet all keys are retrieved\&. On subsequent calls only the keys are retrieved where something was changed inside the key database\&. The other keys stay unchanged in the keyset, even when they were manipulated\&. .PP It is your responsibility to save the original keyset if you need it afterwards\&. .PP If you must get the same keyset again, e\&.g\&. in another thread you need to open a second handle to the key database using \fBkdbOpen()\fP\&. .PP \fBParameters:\fP .RS 4 \fIhandle\fP contains internal information of \fBopened \fP key database .br \fIparentKey\fP parent key holds the information which keys should be get - invalid name gets all keys .br \fIks\fP the (pre-initialized) \fBKeySet\fP returned with all keys found will not be changed on error or if no update is required .RE .PP \fBSee also:\fP .RS 4 \fBksLookupByName()\fP for powerful lookups after the \fBKeySet\fP was retrieved .RE .PP \fBReturns:\fP .RS 4 1 if the keys were retrieved successfully .PP 0 if there was no update - no changes are made to the keyset then .PP -1 on failure - no changes are made to the keyset then .RE .PP .PP .nf #include #include using namespace kdb; int main() { KeySet config; KDB kdb; kdb\&.get(config, "/sw/MyApp"); Key k = config\&.lookup("/sw/MyApp/mykey"); if (k) { std::cout << k << " is " << k\&.get() << std::endl; } else { std::cerr << "No key found" << std::endl; return 1; } } .fi .PP .PP \fBParameters:\fP .RS 4 \fIreturned\fP the keyset where the keys will be in .br \fIkeyname\fP the root keyname which should be used to get keys below it .RE .PP \fBReturn values:\fP .RS 4 \fI0\fP if no key was updated .br \fI1\fP if user or system keys were updated .br \fI2\fP if user and system keys were updated .RE .PP \fBExceptions:\fP .RS 4 \fIKDBException\fP if there were problems with the database .RE .PP \fBSee also:\fP .RS 4 \fBKDB::get\fP (\fBKeySet\fP & returned, \fBKey\fP & parentKey) .RE .PP .SS "int kdb::KDB::get (\fBKeySet\fP &returned, \fBKey\fP &parentKey)\fC [inline]\fP" .PP Retrieve keys in an atomic and universal way, all other \fBkdbGet()\fP Functions rely on that one\&. Get all keys below parentKey inside returned\&. .PP The \fCreturned\fP \fBKeySet\fP must be initialized\&. The \fCreturned\fP \fBKeySet\fP may already contain some keys\&. The new retrieved keys will be appended using \fBksAppendKey()\fP\&. .PP It will fully retrieve all keys under the \fCparentKey\fP folder, with all subfolders and their children\&. .SH "Example" .PP This example demonstrates the typical usecase within an application without updating\&. .PP \fBExample:\fP .RS 4 .PP .nf KeySet *myConfig = ksNew(0); Key *key = keyNew("system/sw/MyApp",KEY_END); KDB *handle = kdbOpen(key); kdbGet(handle, myConfig, key); keySetName(key, "user/sw/MyApp"); kdbGet(handle, myConfig, key); // check for errors in key keyDel(key); 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, 0); // no more affairs with the key database\&. .fi .PP .RE .PP .SH "Details" .PP When no backend could be found (e\&.g\&. no backend mounted) the default backend will be used\&. .PP If you pass NULL on any parameter \fBkdbGet()\fP will fail immediately without doing anything\&. .PP When a backend fails \fBkdbGet()\fP will return -1 without any changes to one of the parameter\&. .SH "Updating" .PP In the first run of kdbGet all keys are retrieved\&. On subsequent calls only the keys are retrieved where something was changed inside the key database\&. The other keys stay unchanged in the keyset, even when they were manipulated\&. .PP It is your responsibility to save the original keyset if you need it afterwards\&. .PP If you must get the same keyset again, e\&.g\&. in another thread you need to open a second handle to the key database using \fBkdbOpen()\fP\&. .PP \fBParameters:\fP .RS 4 \fIhandle\fP contains internal information of \fBopened \fP key database .br \fIparentKey\fP parent key holds the information which keys should be get - invalid name gets all keys .br \fIks\fP the (pre-initialized) \fBKeySet\fP returned with all keys found will not be changed on error or if no update is required .RE .PP \fBSee also:\fP .RS 4 \fBksLookupByName()\fP for powerful lookups after the \fBKeySet\fP was retrieved .RE .PP \fBReturns:\fP .RS 4 1 if the keys were retrieved successfully .PP 0 if there was no update - no changes are made to the keyset then .PP -1 on failure - no changes are made to the keyset then .RE .PP \fBParameters:\fP .RS 4 \fIreturned\fP the keyset where the keys will be in .br \fIparentKey\fP the parentKey of returned .RE .PP \fBReturn values:\fP .RS 4 \fI0\fP if no key was updated .br \fI1\fP if user or system keys were updated .br \fI2\fP if user and system keys were updated .RE .PP \fBExceptions:\fP .RS 4 \fIKDBException\fP if there were problems with the database .RE .PP .SS "void kdb::KDB::open (\fBKey\fP &errorKey)\fC [inline]\fP" .PP Opens the session with the \fBKey\fP database\&. Open the database .PP \fBParameters:\fP .RS 4 \fIerrorKey\fP is useful if you want to get the warnings in the successful case, when no exception is thrown\&. .RE .PP 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 \fC\fBKDB\fP\fP datastructure will be initialized\&. .PP 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 \fBkdbClose()\fP\&. You can use the atexit () handler for it\&. .PP The pointer to the \fC\fBKDB\fP\fP structure returned will be initialized like described above, and it must be passed along on any kdb*() method your application calls\&. .PP Get a \fC\fBKDB\fP\fP handle for every thread using elektra\&. Don't share the handle across threads, and also not the pointer accessing it: .PP .nf thread1 { KDB * h; h = kdbOpen(0); // fetch keys and work with them kdbClose(h, 0); } thread2 { KDB * h; h = kdbOpen(0); // fetch keys and work with them kdbClose(h, 0); } .fi .PP .PP You don't need to use the \fBkdbOpen()\fP if you only want to manipulate plain in-memory \fBKey\fP or \fBKeySet\fP objects without any affairs with the backend key database or when your application loads plugins directly\&. .PP \fBParameters:\fP .RS 4 \fIerrorKey\fP the key which holds errors and warnings which were issued must be given .RE .PP \fBSee also:\fP .RS 4 \fBkdbClose()\fP to end all affairs to the \fBKey\fP database\&. .RE .PP \fBReturns:\fP .RS 4 a \fBKDB\fP pointer on success .PP NULL on failure .RE .PP .SS "int kdb::KDB::set (\fBKeySet\fP &returned, std::string const &keyname)\fC [inline]\fP" .PP Set all keys below keyname\&. .PP If the keyname of the parentKey is invalid (e\&.g\&. empty) all keys will be set\&. .PP Set keys in an atomic and universal way\&. .PP All other kdbSet Functions rely on that one\&. .SH "parentKey" .PP With parentKey you can only store a part of the given keyset\&. .PP .PP .nf KeySet *ks = ksNew(0); Key *parentKey = keyNew("user/app/myapp/default", KEY_END); kdbGet (h, ks, parentKey)); //now only set everything below user if (kdbSet (h, ks, parentKey) == -1) { // in parentKey you can check the error cause // ksCurrent(ks) is the faulty key } ksDel (ks); .fi .PP .PP If you pass a parentKey without a name the whole keyset will be set in an atomic way\&. .SH "Update" .PP Each key is checked with \fBkeyNeedSync()\fP before being actually committed\&. So only changed keys are updated\&. If no key of a backend needs to be synced any affairs to backends omitted and 0 is returned\&. .SH "Error Situations" .PP If some error occurs, \fBkdbSet()\fP will stop\&. In this situation the \fBKeySet\fP internal cursor will be set on the key that generated the error\&. .PP None of the keys are actually commited\&. .PP You should present the error message to the user and let the user decide what to do\&. Possible solutions are: .IP "\(bu" 2 repeat the same kdbSet (for temporary errors) .IP "\(bu" 2 remove the key and set it again (for validation or type errors) .IP "\(bu" 2 change the value and try it again (for validation errors) .IP "\(bu" 2 do a kdbGet and then (for conflicts \&.\&.\&.) .IP " \(bu" 4 set the same keyset again (in favour of what was set by this user) .IP " \(bu" 4 drop the old keyset (in favour of what was set elsewhere) .PP .IP "\(bu" 2 export the configuration into a file (for unresolvable errors) .PP .PP \fBExample of how this method can be used:\fP .RS 4 .PP .nf int i; KeySet *ks; // the KeySet I want to set // fill ks with some keys for (i=0; i< NR_OF_TRIES; i++) // limit to NR_OF_TRIES tries { ret=kdbSet(handle, ks, parentKey); if (ret == -1) { // We got an error\&. Warn user\&. Key *problemKey = ksCurrent(ks); // parentKey has the errorInformation // problemKey is the faulty key (may be null) int userInput = showElektraErrorDialog (parentKey, problemKey); switch (userInput) { case INPUT_REPEAT: continue; case INPUT_REMOVE: ksLookup (ks, parentKey, KDB_O_POP); break; \&.\&.\&. } } } .fi .PP .RE .PP \fBParameters:\fP .RS 4 \fIhandle\fP contains internal information of \fBopened \fP key database .br \fIks\fP a \fBKeySet\fP which should contain changed keys, otherwise nothing is done .br \fIparentKey\fP holds the information below which key keys should be set, see above .RE .PP \fBReturns:\fP .RS 4 1 on success .PP 0 if nothing had to be done .PP -1 on failure .RE .PP \fBSee also:\fP .RS 4 \fBkeyNeedSync()\fP, \fBksNext()\fP, \fBksCurrent()\fP .RE .PP \fBReturn values:\fP .RS 4 \fI0\fP if no key was updated .br \fI1\fP if user or system keys were updated .br \fI2\fP if user and system keys were updated .RE .PP \fBParameters:\fP .RS 4 \fIreturned\fP the keyset where the keys will be in .br \fIkeyname\fP the keyname below the names should be set .RE .PP \fBExceptions:\fP .RS 4 \fIKDBException\fP if there were problems with the database .RE .PP .SS "int kdb::KDB::set (\fBKeySet\fP &returned, \fBKey\fP &parentKey)\fC [inline]\fP" .PP Set all keys below parentKey\&. .PP If the keyname of the parentKey is invalid (e\&.g\&. empty) all keys will be set\&. .PP Set keys in an atomic and universal way\&. .PP All other kdbSet Functions rely on that one\&. .SH "parentKey" .PP With parentKey you can only store a part of the given keyset\&. .PP .PP .nf KeySet *ks = ksNew(0); Key *parentKey = keyNew("user/app/myapp/default", KEY_END); kdbGet (h, ks, parentKey)); //now only set everything below user if (kdbSet (h, ks, parentKey) == -1) { // in parentKey you can check the error cause // ksCurrent(ks) is the faulty key } ksDel (ks); .fi .PP .PP If you pass a parentKey without a name the whole keyset will be set in an atomic way\&. .SH "Update" .PP Each key is checked with \fBkeyNeedSync()\fP before being actually committed\&. So only changed keys are updated\&. If no key of a backend needs to be synced any affairs to backends omitted and 0 is returned\&. .SH "Error Situations" .PP If some error occurs, \fBkdbSet()\fP will stop\&. In this situation the \fBKeySet\fP internal cursor will be set on the key that generated the error\&. .PP None of the keys are actually commited\&. .PP You should present the error message to the user and let the user decide what to do\&. Possible solutions are: .IP "\(bu" 2 repeat the same kdbSet (for temporary errors) .IP "\(bu" 2 remove the key and set it again (for validation or type errors) .IP "\(bu" 2 change the value and try it again (for validation errors) .IP "\(bu" 2 do a kdbGet and then (for conflicts \&.\&.\&.) .IP " \(bu" 4 set the same keyset again (in favour of what was set by this user) .IP " \(bu" 4 drop the old keyset (in favour of what was set elsewhere) .PP .IP "\(bu" 2 export the configuration into a file (for unresolvable errors) .PP .PP \fBExample of how this method can be used:\fP .RS 4 .PP .nf int i; KeySet *ks; // the KeySet I want to set // fill ks with some keys for (i=0; i< NR_OF_TRIES; i++) // limit to NR_OF_TRIES tries { ret=kdbSet(handle, ks, parentKey); if (ret == -1) { // We got an error\&. Warn user\&. Key *problemKey = ksCurrent(ks); // parentKey has the errorInformation // problemKey is the faulty key (may be null) int userInput = showElektraErrorDialog (parentKey, problemKey); switch (userInput) { case INPUT_REPEAT: continue; case INPUT_REMOVE: ksLookup (ks, parentKey, KDB_O_POP); break; \&.\&.\&. } } } .fi .PP .RE .PP \fBParameters:\fP .RS 4 \fIhandle\fP contains internal information of \fBopened \fP key database .br \fIks\fP a \fBKeySet\fP which should contain changed keys, otherwise nothing is done .br \fIparentKey\fP holds the information below which key keys should be set, see above .RE .PP \fBReturns:\fP .RS 4 1 on success .PP 0 if nothing had to be done .PP -1 on failure .RE .PP \fBSee also:\fP .RS 4 \fBkeyNeedSync()\fP, \fBksNext()\fP, \fBksCurrent()\fP .RE .PP \fBReturn values:\fP .RS 4 \fI0\fP if no key was updated .br \fI1\fP if user or system keys were updated .br \fI2\fP if user and system keys were updated .RE .PP \fBParameters:\fP .RS 4 \fIreturned\fP the keyset where the keys are passed to the user .br \fIparentKey\fP the parentKey of returned .RE .PP \fBExceptions:\fP .RS 4 \fIKDBException\fP if there were problems with the database .RE .PP .SH "Author" .PP Generated automatically by Doxygen for Elektra from the source code\&.