| Elektra 0.11.0

Functions
Meta Info Manipulation Methods
Key

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

## Functions
const Key * | keyNextMeta (Key *key)
| Get the next metadata entry of a Key.
int | keyCopyMeta (Key *dest, const Key *source, const char *metaName)
| Do a shallow copy of metadata with name `metaName` from source to dest.
int | keyCopyAllMeta (Key *dest, const Key *source)
| Do a shallow copy of all metadata from source to dest.
const Key * | keyGetMeta (const Key *key, const char *metaName)
| Returns the Key for a metadata entry with name `metaName`.
ssize_t | keySetMeta (Key *key, const char *metaName, const char *newMetaString)
| Set a new metadata Key.
KeySet * | keyMeta (Key *key)
| Returns the KeySet holding the given Key's metadata.

## 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:

- 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 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
}
keyCopyAllMeta
int keyCopyAllMeta(Key *dest, const Key *source)
Do a shallow copy of all metadata from source to dest.
Definition keymeta.c:324

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");
for (elektraCursor it = 0; it < ksGetSize (ks); ++it)
{
current = ksAtCursor (ks, it);
if (needsSharedData (current)) keyCopyAllMeta (current, shared);
}
keyDel (shared);
}
keyDel
int keyDel(Key *key)
A destructor for Key objects.
Definition key.c:459
keyNew
Key * keyNew(const char *name,...)
A practical way to fully create a Key object in one step.
Definition key.c:144
keySetMeta
ssize_t keySetMeta(Key *key, const char *metaName, const char *newMetaString)
Set a new metadata Key.
Definition keymeta.c:442
ksGetSize
ssize_t ksGetSize(const KeySet *ks)
Return the number of Keys that ks contains.
Definition keyset.c:791
ksAtCursor
Key * ksAtCursor(const KeySet *ks, elektraCursor pos)
Return Key at given position pos.
Definition keyset.c:1978

Precondition
  `dest's` metadata is not read-only

Postcondition
  for every metaName present in source: keyGetMeta(source, metaName) == keyGetMeta(dest, metaName)

Parameters

  dest | the destination where the metadata should be copied too
  source | the key where the metadata should be copied from

Return values

  1 | if metadata was successfully copied
  0 | if source did not have any metadata
  -1 | on null pointer of dest or source
  -1 | on 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
}
keyCopyMeta
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:228

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 *shared = keyNew ("/", KEY_END);
keySetMeta(shared, "shared", "this metadata should be shared among many keys");
for (elektraCursor it = 0; it < ksGetSize (ks); ++it)
{
Key * current = ksAtCursor (ks, it);
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

  dest | the destination where the metadata should be copied to
  source | the key where the metadata should be copied from
  metaName | the name of the metadata Key which should be copied

Return values

  1 | if was successfully copied
  0 | if the metadata in dest was removed too
  -1 | on null pointers (source or dest)
  -1 | on memory problems
  -1 | if metadata is read-only

Since
  1.0.0

See also
  keyCopyAllMeta() copies all metadata from `dest` to `src`

## ◆ 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)
keyGetMeta
const Key * keyGetMeta(const Key *key, const char *metaName)
Returns the Key for a metadata entry with name metaName.
Definition keymeta.c:379
keyValue
const void * keyValue(const Key *key)
Return a pointer to the real internal key value.
Definition keyvalue.c:163

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

  key | the Key from which to get metadata
  metaName | the name of the meta information you want the Key from.

Returns
  value of meta-information if meta-information is found

Return values

  0 | if key or metaName is NULL
  0 | if 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;
KeySet * metaKeys;
ssize_t ksSize;
metaKeys = keyMeta (key);
ksSize = ksGetSize (metaKeys);
for (elektraCursor it = 0; it < ksSize; ++it)
{
cur = ksAtCursor (metaKeys, it);
printf ("meta name: %s, meta value: %s\n", keyName (cur), keyString (cur));
}
keyMeta
KeySet * keyMeta(Key *key)
Returns the KeySet holding the given Key's metadata.
Definition keymeta.c:547
keyName
const char * keyName(const Key *key)
Returns a pointer to the abbreviated real internal key name.
Definition elektra/keyname.c:429
keyString
const char * keyString(const Key *key)
Get a pointer to the c-string representing the value.
Definition keyvalue.c:208

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);
ksLookupByName
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:2778

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.
  If the key has not metadata keyset, it will be allocated

Postcondition
  for the returned KeySet ks: keyGetMeta(key, metaName) == ksLookupByName(ks, metaName)
  `key` contains a KeySet for the metadata

Parameters

  key | the Key from which to get the metadata KeySet

Returns
  the KeySet holding the metadata

Return values

  0 | if the Key is 0

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

  key | the Key object to work with

Returns
  a key containing metadata

Return values

  0 | when the last Key has been reached
  0 | when Key is a NULL pointer

Since
  1.0.0

## ◆ 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

  key | Key whose metadata should be set
  metaName | name of the metadata Key that should be set
  newMetaString | new value for the metadata Key

Returns
  size (>0) of `newMetaString` if metadata has been successfully added

Return values

  0 | if the meta-information for metaName was removed
  -1 | if key or metaName is 0
  -1 | if system is out of memory
  -1 | if `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