Elektra  0.8.11
Functions
API Proposals for Elektra
Proposals for Elektra

for kdb.h. More...

Collaboration diagram for API Proposals for Elektra:

Functions

const void * keyUnescapedName (const Key *key)
 This keyname is null separated and does not use backslash for escaping.
 
ssize_t keyGetUnescapedNameSize (const Key *key)
 return size of unescaped name
 
ssize_t keySetStringF (Key *key, const char *format,...)
 Set a formatted string.
 
int elektraArrayIncName (Key *key)
 Increment the name of the key by one.
 
int elektraKsToMemArray (KeySet *ks, Key **buffer)
 Builds an array of pointers to the keys in the supplied keyset.
 
int elektraKsFilter (KeySet *result, KeySet *input, int(*filter)(const Key *k, void *argument), void *argument)
 return only those keys from the given keyset that pass the supplied filter function with the supplied argument
 
KeySet * elektraRenameKeys (KeySet *config, const char *name)
 Takes the first key and cuts off this common part for all other keys, instead name will be prepended.
 
elektraNamespace keyGetNamespace (const Key *key)
 For currently valid namespaces see elektraNamespace.
 
int keyLock (Key *key, enum elektraLockOptions what)
 Permanently locks a part of the key.
 
KeySet * elektraArrayGet (const Key *arrayParent, KeySet *keys)
 Return all the array keys below the given arrayparent The arrayparent itself is not returned.
 
Key * elektraArrayGetNextKey (KeySet *arrayKeys)
 Return the next key in the given array.
 
KeySet * elektraKeyGetMetaKeySet (const Key *key)
 Return meta data as keyset.
 
Key * ksPrev (KeySet *ks)
 Returns the previous Key in a KeySet.
 
Key * ksPopAtCursor (KeySet *ks, cursor_t pos)
 Pop key at given cursor position.
 

Detailed Description

for kdb.h.

Warning
Do not use these methods if you do not want to depend on exactly the Elektra version your binary was built for.

These methods are a technical preview of what might be added in future Elektra releases. It is a requirement that methods are first added here, before they are added to the public API.

Usually, names in proposal stage should be prefixed with elektra to clearly mark that the signature is likely to be changed and not yet ABI compatible.

Function Documentation

KeySet* elektraArrayGet ( const Key *  arrayParent,
KeySet *  keys 
)

Return all the array keys below the given arrayparent The arrayparent itself is not returned.

For example, if user/config/# is an array, user/config is the array parent. Only the direct array keys will be returned. This means that for example user/config/#1/key will not be included, but only user/config/#1.

A new keyset will be allocated for the resulting keys. This means that the caller must ksDel the resulting keyset.

Parameters
arrayParentthe parent of the array to be returned
keysthe keyset containing the array keys.
Returns
a keyset containing the arraykeys (if any)
Return values
NULLon NULL pointers
Key* elektraArrayGetNextKey ( KeySet *  arrayKeys)

Return the next key in the given array.

The function will automatically allocate memory for a new key and name it accordingly.

Precondition
The supplied keyset must contain only valid array keys.

The caller has to keyDel the resulting key.

Parameters
arraykeysthe array where the new key will belong to
Returns
the new array key on success
Return values
NULLif the passed array is empty
NULLon NULL pointers or if an error occurs
int elektraArrayIncName ( Key *  key)

Increment the name of the key by one.

Alphabetical order will remain

e.g. user/abc/#9 will be changed to user/abc/#_10

For the start: user/abc/# will be changed to user/abc/#0

Parameters
keywhich base name will be incremented
Return values
-1on error (e.g. too large array, not validated array)
0on success
KeySet* elektraKeyGetMetaKeySet ( const Key *  key)

Return meta data as keyset.

Parameters
keythe key object to work with
Returns
a duplication of the keyset representing the meta data
int elektraKsFilter ( KeySet *  result,
KeySet *  input,
int(*)(const Key *k, void *argument)  filter,
void *  argument 
)

return only those keys from the given keyset that pass the supplied filter function with the supplied argument

Parameters
resultthe keyset that should contain the filtered keys
inputthe keyset whose keys should be filtered
filtera function pointer to a function that will be used to filter the keyset. A key will be taken if the function returns a value greater than 0.
argumentan argument that will be passed to the filter function each time it is called
Returns
the number of filtered keys if the filter function always returned a positive value, -1 otherwise
Return values
NULLon NULL pointer
int elektraKsToMemArray ( KeySet *  ks,
Key **  buffer 
)

Builds an array of pointers to the keys in the supplied keyset.

The keys are not copied, calling keyDel may remove them from the keyset.

The size of the buffer can be easily allocated via ksGetSize. Example:

KeySet *ks = somekeyset;
Key **keyArray = calloc (ksGetSize(ks), sizeof (Key *));
elektraKsToMemArray (ks, keyArray);
... work with the array ...
free (keyArray);
Parameters
ksthe keyset object to work with
bufferthe buffer to put the result into
Returns
the number of elements in the array if successful
a negative number on null pointers or if an error occurred
KeySet* elektraRenameKeys ( KeySet *  config,
const char *  name 
)

Takes the first key and cuts off this common part for all other keys, instead name will be prepended.

Returns
a new allocated keyset with keys in user namespace.

The first key is removed in the resulting keyset.

elektraNamespace keyGetNamespace ( const Key *  key)

For currently valid namespaces see elektraNamespace.

Since
0.8.10 Added method to kdbproposal.h

To handle every possible cases (including namespaces) a key can have:

switch (keyGetNamespace(k))
{
printf ("spec namespace\n");
break;
printf ("proc namespace\n");
break;
printf ("dir namespace\n");
break;
printf ("user namespace\n");
break;
printf ("system namespace\n");
break;
printf ("empty name\n");
break;
printf ("no key\n");
break;
printf ("meta key\n");
break;
printf ("cascading key\n");
break;
}

To loop over all valid namespaces use:

{
// work with namespace
printf ("%d\n", ns);
}
Note
This method might be enhanced. You do not have any guarantee that, when for a specific name KEY_NS_META is returned today, that it still will be returned after the next recompilation. So make sure that your compiler gives you a warning for unhandled switches (gcc: -Wswitch or -Wswitch-enum if you want to handle default) and look out for those warnings.
Parameters
keythe key object to work with
Returns
the namespace of a key.
ssize_t keyGetUnescapedNameSize ( const Key *  key)

return size of unescaped name

Parameters
keythe object to work with
Return values
-1on null pointer
0if no name
int keyLock ( Key *  key,
enum elektraLockOptions  what 
)

Permanently locks a part of the key.

This can be:

  • KEY_FLAG_LOCK_NAME to lock the name
  • KEY_FLAG_LOCK_VALUE to lock the value
  • KEY_FLAG_LOCK_META to lock the meta data

To unlock the key, duplicate it.

It is also possible to lock when the key is created with keyNew().

Some data structures need to lock the key (most likely its name), so that the ordering does not get confused.

Parameters
keywhich name should be locked
See Also
keyNew(), keyDup(), ksAppendKey()
Return values
>0the bits that were successfully locked
0if everything was locked before
-1if it could not be locked (nullpointer)
ssize_t keySetStringF ( Key *  key,
const char *  format,
  ... 
)

Set a formatted string.

Parameters
keythe key to set the string value
formatNULL-terminated text format string
...more arguments
Returns
the size of the string as set (with including 0)
const void* keyUnescapedName ( const Key *  key)

This keyname is null separated and does not use backslash for escaping.

This name is essential if you want to iterate over parts of the key name, want to compare keynames and want to check relations of keys in the hierarchy.

Parameters
keythe object to work with
Return values
0on null pointers
Returns
the name in its unescaped form
Key* ksPopAtCursor ( KeySet *  ks,
cursor_t  pos 
)

Pop key at given cursor position.

Parameters
ksthe keyset to pop key from
cwhere to pop

The internal cursor will be rewinded using ksRewind(). You can use ksGetCursor() and ksSetCursor() jump back to the previous position. e.g. to pop at current position within ksNext() loop:

cursor_t c = ksGetCursor(ks);
ksSetCursor(ks, c);
ksPrev(ks); // to have correct key after next ksNext()
Warning
do not use, will be superseded by external iterator API
Returns
the popped key
Return values
0if ks is 0
Key* ksPrev ( KeySet *  ks)

Returns the previous Key in a KeySet.

KeySets have an internal cursor that can be reset with ksRewind(). Every time ksPrev() is called the cursor is decremented and the new current Key is returned.

You'll get a NULL pointer if the key before begin of the KeySet was reached.

Don't delete the key, use ksPop() if you want to delete it.

Returns
the new current Key
See Also
ksRewind(), ksCurrent()