Elektra  0.9.9
Functions
Meta Info Manipulation Methods

Methods to do various operations on Key metadata. More...

Collaboration diagram for Meta Info Manipulation Methods:

Functions

int keyRewindMeta (Key *key)
 Rewind the internal iterator to the first entry in metadata keyset. More...
 
const Key * keyNextMeta (Key *key)
 Get the next metadata entry of a Key. More...
 
const Key * keyCurrentMeta (const Key *key)
 Returns the metadata Key at the internal iterator's current position. More...
 
int keyCopyMeta (Key *dest, const Key *source, const char *metaName)
 Do a shallow copy of metadata with name metaName from source to dest. More...
 
int keyCopyAllMeta (Key *dest, const Key *source)
 Do a shallow copy of all metadata from source to dest. More...
 
const Key * keyGetMeta (const Key *key, const char *metaName)
 Returns the Key for a metadata entry with name metaName. More...
 
ssize_t keySetMeta (Key *key, const char *metaName, const char *newMetaString)
 Set a new metadata Key. More...
 
KeySet * keyMeta (Key *key)
 Returns the KeySet holding the given Key's metadata. More...
 

Detailed Description

Methods to do various operations on Key metadata.

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:

Examples for metadata

File system information (see stat(2) for more information):

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 metakey "app" describes to which application a key belongs. It can be used to remove keys from an application no longer installed.

The metakey "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

◆ keyCopyAllMeta()

int keyCopyAllMeta ( Key *  dest,
const Key *  source 
)

Do a shallow copy of all metadata from source to dest.

The key dest will additionally have all metadata the source had. Metadata not present in source will not be changed. Metadata which was present in source and dest will be overwritten. If the dest Key is read-only it will not be changed.

For example the metadata type is copied into the Key k:

void l (Key * k)
{
// receive copy
keyCopyAllMeta (k, copy);
// the caller will see the changed key k
// with all the metadata from copy
}
int keyCopyAllMeta(Key *dest, const Key *source)
Do a shallow copy of all metadata from source to dest.
Definition: keymeta.c:399

The main purpose of this function is for plugins or applications which want to add the same metadata 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 metadata for each.

To avoid that problem you can use keyCopyAllMeta() or keyCopyMeta():

void o (KeySet * ks)
{
Key * current;
Key * shared = keyNew ("/", KEY_END);
keySetMeta (shared, "shared1", "this metadata should be shared among many keys");
keySetMeta (shared, "shared2", "this metadata should be shared among many keys also");
keySetMeta (shared, "shared3", "this metadata should be shared among many keys too");
ksRewind (ks);
while ((current = ksNext (ks)) != 0)
{
if (needsSharedData (current)) keyCopyAllMeta (current, shared);
}
keyDel (shared);
}
int keyDel(Key *key)
A destructor for Key objects.
Definition: key.c:482
Key * keyNew(const char *name,...)
A practical way to fully create a Key object in one step.
Definition: key.c:138
@ KEY_END
Definition: kdbenum.c:95
ssize_t keySetMeta(Key *key, const char *metaName, const char *newMetaString)
Set a new metadata Key.
Definition: keymeta.c:517
Key * ksNext(KeySet *ks)
Returns the next Key in a KeySet.
Definition: keyset.c:1609
int ksRewind(KeySet *ks)
Rewinds the KeySet internal cursor.
Definition: keyset.c:1571
Precondition
dest's metadata is not read-only
Postcondition
for every metaName present in source: keyGetMeta(source, metaName) == keyGetMeta(dest, metaName)
Parameters
destthe destination where the metadata should be copied too
sourcethe key where the metadata should be copied from
Return values
1if metadata was successfully copied
0if source did not have any metadata
-1on null pointer of dest or source
-1on memory problems
Since
1.0.0
See also
keyCopyMeta() for copying one metadata Key from dest to source

◆ keyCopyMeta()

int keyCopyMeta ( Key *  dest,
const Key *  source,
const char *  metaName 
)

Do a shallow copy of metadata with name metaName from source to dest.

Afterwards source and dest will have the same metadata referred with metaName. If the Key with name metaName doesn't exist in source - it gets deleted in dest.

For example the metadata type is copied into the Key k.

void l(Key *k)
{
// receive c
keyCopyMeta(k, c, "type");
// the caller will see the changed key k
// with the metadata "type" from c
}
int keyCopyMeta(Key *dest, const Key *source, const char *metaName)
Do a shallow copy of metadata with name metaName from source to dest.
Definition: keymeta.c:303

The main purpose of this function is for plugins or applications, which want to add the same metadata to n keys. When you do that keySetMeta() will take n times the memory for the key. This can be a considerable amount of memory for many keys with some metadata for each.

To avoid that problem you can use keyCopyAllMeta() or keyCopyMeta().

void o(KeySet *ks)
{
Key *current;
Key *shared = keyNew ("/", KEY_END);
keySetMeta(shared, "shared", "this metadata should be shared among many keys");
ksRewind(ks);
while ((current = ksNext(ks)) != 0)
{
if (needs_shared_data(current)) keyCopyMeta(current, shared, "shared");
}
}
Precondition
dest's metadata is not read-only
Postcondition
keyGetMeta(source, metaName) == keyGetMeta(dest, metaName)
Parameters
destthe destination where the metadata should be copied to
sourcethe key where the metadata should be copied from
metaNamethe name of the metadata Key which should be copied
Return values
1if was successfully copied
0if the metadata in dest was removed too
-1on null pointers (source or dest)
-1on memory problems
-1if metadata is read-only
Since
1.0.0
See also
keyCopyAllMeta() copies all metadata from dest to src

◆ keyCurrentMeta()

const Key* keyCurrentMeta ( const Key *  key)

Returns the metadata Key at the internal iterator's current position.

The returned pointer is NULL if the end has been reached or after calling ksRewind().

Note
You must not delete or change the returned key, use keySetMeta() if you want to delete or change it.
Parameters
keyKey to get the current metadata from
Returns
a buffer to the value pointed by key's cursor
Return values
0on NULL pointer
Since
1.0.0
See also
keyNextMeta() for getting the next value
keyRewindMeta() for rewinding the internal iterator
ksCurrent() KeySets's equivalent function for getting the current Key

◆ keyGetMeta()

const Key* keyGetMeta ( const Key *  key,
const char *  metaName 
)

Returns the Key for a metadata entry with name metaName.

You are not allowed to modify the resulting key.

If metaName does not start with 'meta:/', it will be prefixed with 'meta:/'.

Key metaData = keyGetMeta(k, "type")
// keyType == "boolean"
char keyType[] = keyValue(metaData)
const Key * keyGetMeta(const Key *key, const char *metaName)
Returns the Key for a metadata entry with name metaName.
Definition: keymeta.c:454
const void * keyValue(const Key *key)
Return a pointer to the real internal key value.
Definition: keyvalue.c:168
Note
You must not delete or change the returned key, use keySetMeta() if you want to delete or change it.
Precondition
key contains metadata
metaName is prefixed with "meta:/"
Parameters
keythe Key from which to get metadata
metaNamethe name of the meta information you want the Key from.
Returns
value of meta-information if meta-information is found
Return values
0if key or metaName is NULL
0if no such metaName is found
Since
1.0.0
See also
keySetMeta() for setting metadata
keyMeta() for getting the KeySet containing metadata

◆ keyMeta()

KeySet* keyMeta ( Key *  key)

Returns the KeySet holding the given Key's metadata.

Use keySetMeta() to populate the metadata KeySet of a Key.

Key * key = keyNew ("user:/test/key", KEY_END);
keySetMeta (key, "meta1", "value1");
keySetMeta (key, "meta2", "value2");

Iterate the returned metadata KeySet like any other KeySet.

Key * cur;
ksRewind (keyMeta (key));
while ((cur = ksNext (keyMeta (key))) != NULL)
{
printf ("meta name: %s, meta value: %s\n", keyName (cur), keyString (cur));
}
KeySet * keyMeta(Key *key)
Returns the KeySet holding the given Key's metadata.
Definition: keymeta.c:637
const char * keyName(const Key *key)
Returns a pointer to the abbreviated real internal key name.
Definition: elektra/keyname.c:256
const char * keyString(const Key *key)
Get a pointer to the c-string representing the value.
Definition: keyvalue.c:213

Use ksLookup() or keyGetMeta() to retrieve a single value for a given Key.

Key * lookupKey = ksLookupByName (keyMeta (key), "meta2", 0);
printf ("meta name: %s, meta value: %s\n", keyName (lookupKey), keyString (lookupKey));
keyDel (key);
Key * ksLookupByName(KeySet *ks, const char *name, elektraLookupFlags options)
Convenience method to look for a Key contained in ks with name name.
Definition: keyset.c:2616
Note
You are not allowed to modify the name of KeySet's Keys or delete them.
You must not delete the returned KeySet.
Adding a key with metadata to the KeySet is an error.
Postcondition
for the returned KeySet ks: keyGetMeta(key, metaName) == ksLookupByName(ks, metaName)
key contains a KeySet for the metadata
Parameters
keythe Key from which to get the metadata KeySet
Returns
the KeySet holding the metadata
Return values
0if the Key is 0
0if the Key has no metadata
Since
1.0.0
See also
keySetMeta() for setting a metadata Key
keyGetMeta() for getting a metadata Key

◆ keyNextMeta()

const Key* keyNextMeta ( Key *  key)

Get the next metadata entry of a Key.

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 metadata 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
keythe Key object to work with
Returns
a key containing metadata
Return values
0when the last Key has been reached
0when Key is a NULL pointer
Since
1.0.0
See also
ksNext() for pedant in iterator interface of KeySet
keyRewindMeta() for rewinding the internal iterator
keyCurrentMeta() for getting the current metadata Key

◆ keyRewindMeta()

int keyRewindMeta ( Key *  key)

Rewind the internal iterator to the first entry in metadata keyset.

Use this function to set the cursor to the beginning of the Key Meta Infos. keyCurrentMeta() will always return NULL after rewinding, so you need to call keyNextMeta() first.

Key *key;
const Key *meta;
while ((meta = keyNextMeta (key))!=0)
{
printf ("name: %s, value: %s", keyName(meta), keyString(meta));
}
const Key * keyNextMeta(Key *key)
Get the next metadata entry of a Key.
Definition: keymeta.c:197
int keyRewindMeta(Key *key)
Rewind the internal iterator to the first entry in metadata keyset.
Definition: keymeta.c:158
Parameters
keyKey whose internal iterator should be rewinded
Return values
0on success
0if there is no metadata for that key (keyNextMeta() will always return 0 in that case)
-1on NULL pointer
Since
1.0.0
See also
keyNextMeta(), keyCurrentMeta() for iterating after rewinding
ksRewind() KeySet's equivalent function for rewinding

◆ keySetMeta()

ssize_t keySetMeta ( Key *  key,
const char *  metaName,
const char *  newMetaString 
)

Set a new metadata Key.

Will set a new metadata pair with name metaName and value newMetaString.

Will add a new metadata Key, if metaName was unused until now.

It will modify an existing Pair of metadata if metaName was already present.

It will remove a metadata Key if newMetaString is 0.

If metaName does not start with 'meta:/', it will be prefixed with 'meta:/'.

Precondition
metaName is prefixed with "meta:/"
key's metadata is not read-only
Postcondition
The value in key's metadata Keyset for metaName is newMetaString
Parameters
keyKey whose metadata should be set
metaNamename of the metadata Key that should be set
newMetaStringnew value for the metadata Key
Returns
size (>0) of newMetaString if metadata has been successfully added
Return values
0if the meta-information for metaName was removed
-1if key or metaName is 0
-1if system is out of memory
-1if metaName is not a valid metadata name
Since
1.0.0
See also
keyGetMeta() for getting the value of a metadata Key
keyMeta() for getting the KeySet containing metadata