Provided by: elektra-doc_0.8.14-5_all 
NAME
keymeta - Meta Info Manipulation Methods
Methods to do various operations on Key metainfo.
Functions
int keyRewindMeta (Key *key)
Rewind the internal iterator to first meta data.
const Key * keyNextMeta (Key *key)
Iterate to the next meta information.
const Key * keyCurrentMeta (const Key *key)
Returns the Value of a Meta-Information which is current.
int keyCopyMeta (Key *dest, const Key *source, const char *metaName)
Do a shallow copy of meta data from source to dest.
int keyCopyAllMeta (Key *dest, const Key *source)
Do a shallow copy of all meta data from source to dest.
const Key * keyGetMeta (const Key *key, const char *metaName)
Returns the Value of a Meta-Information given by name.
ssize_t keySetMeta (Key *key, const char *metaName, const char *newMetaString)
Set a new Meta-Information.
Detailed Description
Methods to do various operations on Key metainfo.
To use them:
#include <kdb.h>
Next to Name (key and owner) and Value (data and comment) there is the so called meta information
inside every key.
Key meta information are an unlimited number of key/value pairs strongly related to a key. It main
purpose is to give keys special semantics, so that plugins can treat them differently.
Metakey, as opposed to Key, deliberately has following limitations:
• no null values
• no binary data
• no modification of references (COW)
• no guarantee of ordering
Examples for metadata
File system information (see stat(2) for more information):
• uid: the user id (positive number)
• gid: the group id (positive number)
• mode: filesystem-like mode permissions (positive octal number)
• atime: When was the key accessed the last time.
• mtime: When was the key modified the last time.
• ctime: When the uid, gid or mode of a key changes. (times are represented through a positive number as
unix timestamp)
The comment can contain userdata which directly belong to that key. The name of the meta information is
'comment' for a general purpose comment about the key. Multi-Language comments are also supported by
appending [LANG] to the name.
Validators are regular expressions which are tested against the key value. The metakey 'validator' can
hold a regular expression which will be matched against.
Types can be expressed with the meta information 'type'.
The relevance of the key can be tagged with a value from -20 to 20. Negative numbers are the more
important and must be present in order to start the program.
A version of a key may be stored with 'version'. Its format is full.major.minor where all of these are
integers.
The order inside a persistent storage can be described with the tag 'order' which contains a positive
number.
The meta key 'app' describes to which application a key belongs. It can be used to remove keys from an
application no longer installed.
The meta key 'path' describes where the key is physically stored.
The 'owner' is the user that owns the key. It only works for the user/ hierarchy. It rather says where
the key is stored and says nothing about the filesystem properties.
Function Documentation
int keyCopyAllMeta (Key * dest, const Key * source)
Do a shallow copy of all meta data from source to dest. The key dest will additionally have all meta data
the source had. Meta data not present in source will not be changed. Meta data which was present in
source and dest will be overwritten.
For example the meta data type is copied into the Key k:
void l(Key *k)
{
// receive c
keyCopyAllMeta(k, c);
// the caller will see the changed key k
// with all the metadata from c
}
The main purpose of this function is for plugins or applications which want to add the same meta data to
n keys. When you do that with keySetMeta() it will take n times the memory for the key. This can be
considerable amount of memory for many keys with some meta data for each.
To avoid that problem you can use keyCopyAllMeta() or keyCopyMeta():
void o(KeySet *ks)
{
Key *current;
Key *shared = keyNew (0);
keySetMeta(shared, "shared1", "this meta data should be shared among many keys");
keySetMeta(shared, "shared2", "this meta data should be shared among many keys also");
keySetMeta(shared, "shared3", "this meta data should be shared among many keys too");
ksRewind(ks);
while ((current = ksNext(ks)) != 0)
{
if (needsSharedData(current)) keyCopyAllMeta(current, shared);
}
keyDel(shared);
}
Postcondition:
for every metaName present in source: keyGetMeta(source, metaName) == keyGetMeta(dest, metaName)
Return values:
1 if was successfully copied
0 if source did not have any meta data
-1 on null pointer of dest or source
-1 on memory problems
Parameters:
dest the destination where the meta data should be copied too
source the key where the meta data should be copied from
int keyCopyMeta (Key * dest, const Key * source, const char * metaName)
Do a shallow copy of meta data from source to dest. The key dest will have the same meta data referred
with metaName afterwards then source.
For example the meta data type is copied into the Key k.
1 void l(Key *k)
2 {
3 // receive c
4 keyCopyMeta(k, c, "type");
5 // the caller will see the changed key k
6 // with the metadata "type" from c
7 }
The main purpose of this function is for plugins or applications which want to add the same meta data to
n keys. When you do that with keySetMeta() it will take n times the memory for the key. This can be
considerable amount of memory for many keys with some meta data for each.
To avoid that problem you can use keyCopyAllMeta() or keyCopyMeta().
1 void o(KeySet *ks)
2 {
3 Key *current;
4 Key *shared = keyNew (0);
5 keySetMeta(shared, "shared", "this meta data should be shared among many keys");
6
7 ksRewind(ks);
8 while ((current = ksNext(ks)) != 0)
9 {
10 if (needs_shared_data(current)) keyCopyMeta(current, shared, "shared");
11 }
12 }
Postcondition:
keyGetMeta(source, metaName) == keyGetMeta(dest, metaName)
Return values:
1 if was successfully copied
0 if the meta data in dest was removed too
-1 on null pointers (source or dest)
-1 on memory problems
Parameters:
dest the destination where the meta data should be copied too
source the key where the meta data should be copied from
metaName the name of the meta data which should be copied
const Key* keyCurrentMeta (const Key * key)
Returns the Value of a Meta-Information which is current. The pointer is NULL if you reached the end or
after ksRewind().
Note:
You must not delete or change the returned key, use keySetMeta() if you want to delete or change it.
Parameters:
key the key object to work with
Returns:
a buffer to the value pointed by key's cursor
Return values:
0 on NULL pointer
See also:
keyNextMeta(), keyRewindMeta()
ksCurrent() for pedant in iterator interface of KeySet
const Key* keyGetMeta (const Key * key, const char * metaName)
Returns the Value of a Meta-Information given by name. This is a much more efficient version of
keyGetMeta(). But unlike with keyGetMeta you are not allowed to modify the resulting string.
1 int f(Key *k)
2 {
3 if (!strcmp(keyValue(keyGetMeta(k, "type")), "boolean"))
4 {
5 // the type of the key is boolean
6 }
7 }
Note:
You must not delete or change the returned key, use keySetMeta() if you want to delete or change it.
Parameters:
key the key object to work with
metaName the name of the meta information you want the value from
Return values:
0 if the key or metaName is 0
0 if no such metaName is found
Returns:
value of Meta-Information if Meta-Information is found
See also:
keyGetMeta(), keySetMeta()
const Key* keyNextMeta (Key * key)
Iterate to the next meta information. Keys have an internal cursor that can be reset with
keyRewindMeta(). Every time keyNextMeta() is called the cursor is incremented and the new current Name of
Meta Information is returned.
You'll get a NULL pointer if the meta information after the end of the Key was reached. On subsequent
calls of keyNextMeta() it will still return the NULL pointer.
The key internal cursor will be changed, so it is not const.
Note:
That the resulting key is guaranteed to have a value, because meta information has no binary or null
pointer semantics.
You must not delete or change the returned key, use keySetMeta() if you want to delete or change it.
Parameters:
key the key object to work with
Returns:
a key representing meta information
Return values:
0 when the end is reached
0 on NULL pointer
See also:
ksNext() for pedant in iterator interface of KeySet
int keyRewindMeta (Key * key)
Rewind the internal iterator to first meta data. Use it to set the cursor to the beginning of the Key
Meta Infos. keyCurrentMeta() will then always return NULL afterwards. So you want to keyNextMeta() first.
1 Key *key;
2 const Key *meta;
3
4 keyRewindMeta (key);
5 while ((meta = keyNextMeta (key))!=0)
6 {
7 printf ("name: %s, value: %s", keyName(meta), (const char*)keyValue(meta));
8 }
Parameters:
key the key object to work with
Return values:
0 on success
0 if there is no meta information for that key (keyNextMeta() will always return 0 in that case)
-1 on NULL pointer
See also:
keyNextMeta(), keyCurrentMeta()
ksRewind() for pedant in iterator interface of KeySet
ssize_t keySetMeta (Key * key, const char * metaName, const char * newMetaString)
Set a new Meta-Information. Will set a new Meta-Information pair consisting of metaName and
newMetaString.
Will add a new Pair for Meta-Information if metaName was not added up to now.
It will modify a existing Pair of Meta-Information if the the metaName was inserted already.
It will remove a meta information if newMetaString is 0.
Parameters:
key the key object to work with
metaName the name of the meta information where you want to change the value
newMetaString the new value for the meta information
Return values:
-1 on error if key or metaName is 0, out of memory or names are not valid
0 if the Meta-Information for metaName was removed
Returns:
size (>0) of newMetaString if Meta-Information was successfully added
See also:
keyGetMeta()
Author
Generated automatically by Doxygen for Elektra from the source code.
Version 0.8.14 Tue Dec 15 2015 keymeta(3elektra)