$darkmode
Elektra 0.9.12
Functions
Meta Data proposal+compatibility

Meta data proposal+compatibility methods. More...

Functions

const char * keyComment (const Key *key)
 Return a pointer to the real internal key comment. More...
 
ssize_t keyGetCommentSize (const Key *key)
 Calculates number of bytes needed to store a key comment, including final NULL. More...
 
ssize_t keyGetComment (const Key *key, char *returnedComment, size_t maxSize)
 Get the key comment. More...
 
ssize_t keySetComment (Key *key, const char *newComment)
 Set a comment for a key. More...
 
int elektraKeyCmpOrder (const Key *ka, const Key *kb)
 Compare the order metadata of two keys. More...
 
void elektraMetaArrayAdd (Key *key, const char *metaName, const char *value)
 creates an metadata array or appends another element to an existing metadata array e.g. More...
 
KeySet * elektraMetaArrayToKS (Key *key, const char *metaName)
 Create a KeySet from a metakey array. More...
 
int elektraSortTopology (KeySet *ks, Key **array)
 topological sorting More...
 
char * elektraMetaArrayToString (const Key *key, const char *metaName, const char *delim)
 returns the metakey array as a string separated by delim More...
 

Detailed Description

Meta data proposal+compatibility methods.

In versions before Elektra 0.8 only limited metadata was available. Now any metadata can be added. These API methods are implementations of the 0.7 API using 0.8 metadata.

Additionally, new suggestions can be made here.

It is planned that these methods will be generated from doc/METADATA.ini and moved to a separate library. Currently, you should better avoid the methods and directly use metainfo instead.

Function Documentation

◆ elektraKeyCmpOrder()

int elektraKeyCmpOrder ( const Key *  ka,
const Key *  kb 
)

Compare the order metadata of two keys.

Returns
a number less than, equal to or greater than zero if the order of k1 is found, respectively, to be less than, to match, or be greater than the order of k2. If one key is NULL, but the other isn't, the key which is not NULL is considered to be greater. If both keys are NULL, they are considered to be equal. If one key does have an order metadata but the other has not, the key with the metadata is considered greater. If no key has metadata, they are considered to be equal.
Parameters
kakey to compare with
kbother key to compare with

◆ elektraMetaArrayAdd()

void elektraMetaArrayAdd ( Key *  key,
const char *  metaName,
const char *  value 
)

creates an metadata array or appends another element to an existing metadata array e.g.

Key *key = keyNew("user:/test", KEY_END);
elektraMetaArrayAdd(key, "test", "val0");
// key now has "test/#0" with value "val0" as metadata
elektraMetaArrayAdd(key, "test", "val1");
// appends "test/#1" with value "val1" to key
Key * keyNew(const char *name,...)
A practical way to fully create a Key object in one step.
Definition: key.c:144
@ KEY_END
Definition: kdbenum.c:95
void elektraMetaArrayAdd(Key *key, const char *metaName, const char *value)
creates an metadata array or appends another element to an existing metadata array e....
Definition: meta.c:296
Parameters
keythe key the metadata should be added to
metaNamethe name of the metakey array parent
valuethe value of the newly appended metakey

◆ elektraMetaArrayToKS()

KeySet* elektraMetaArrayToKS ( Key *  key,
const char *  metaName 
)

Create a KeySet from a metakey array.

For example, the following function call

keyNew ("/a", KEY_VALUE, "b, c",
KEY_META, "dep", "#1",
KEY_META, "dep/#0", "/b",
KEY_META, "dep/#1", "/c", KEY_END),
"dep");
@ KEY_META
Definition: kdbenum.c:92
@ KEY_VALUE
Definition: kdbenum.c:88
KeySet * elektraMetaArrayToKS(Key *key, const char *metaName)
Create a KeySet from a metakey array.
Definition: meta.c:343

returns a KeySet containing the keys dep with value #1, "dep/#0" with value "/b" and "dep/#1" with value "/c".

If no metakey array is found, null is returned. The returned KeySet must be freed with ksDel

Returns
a keyset containing all the metakeys of the metakey array or null if no metakey array is found
Parameters
keythe key containing the metakey array
metaNamethe name of the metakey array parent

◆ elektraMetaArrayToString()

char* elektraMetaArrayToString ( const Key *  key,
const char *  metaName,
const char *  delim 
)

returns the metakey array as a string separated by delim

Parameters
keythe key containing the metakey array
metaNamethe name of the metakey array parent
delimdelimiter for the records in the returned string
Returns
a string containing all metakey values separated by "delim"

◆ elektraSortTopology()

int elektraSortTopology ( KeySet *  ks,
Key **  array 
)

topological sorting

Parameters
arraythe array where the sorted keys will be stored in topological order. Nothing will be written into an array if
ksis the keyset that should be sorted. Dependencies and order is defined by metakeys.
  • the "dep/#" metakeys e.g. the Key *k = keyNew ("/a", KEY_VALUE, "b, c", KEY_META, "dep", "#1", KEY_META, "dep/#0", "/b", KEY_META, "dep/#1", "/c", KEY_END), "dep"); depends on Key "/b" and Key "/c".
  • if "order" metakeys are defined for the keys the algorithm tries to resolves them by that order using lexical comparison. You should prefer #0 array syntax.

Duplicated and reflexive dep entries are ignored.

The algorithm used is a mixture of Kahn and BFS. Furthermore the algorithm does not use recursion.

First a BFS with the keys sorted by "order" is used. Then all dependencies (recursively) of every key is collected.

Return values
1on success
0for cycles
-1for invalid dependencies

◆ keyComment()

const char* keyComment ( const Key *  key)

Return a pointer to the real internal key comment.

This is a much more efficient version of keyGetComment() and you should use it if you are responsible enough to not mess up things. You are not allowed to change anything in the memory region the returned pointer points to.

keyComment() returns "" when there is no keyComment. The reason is

key=keyNew(0);
keySetComment(key,"");
keyComment(key); // you would expect "" here
keyDel(key);
int keyDel(Key *key)
A destructor for Key objects.
Definition: key.c:462
ssize_t keySetComment(Key *key, const char *newComment)
Set a comment for a key.
Definition: meta.c:214
const char * keyComment(const Key *key)
Return a pointer to the real internal key comment.
Definition: meta.c:91

See keySetComment() for more information on comments.

Note
Note that the Key structure keeps its own size field that is calculated by library internal calls, so to avoid inconsistencies, you must never use the pointer returned by keyComment() method to set a new value. Use keySetComment() instead.
Parameters
keythe key object to work with
Returns
a pointer to the internal managed comment
Return values
""when there is no comment
0on NULL pointer
See also
keyGetCommentSize() for size and keyGetComment() as alternative

◆ keyGetComment()

ssize_t keyGetComment ( const Key *  key,
char *  returnedComment,
size_t  maxSize 
)

Get the key comment.

Comments

A Key comment is description for humans what this key is for. It may be a textual explanation of valid values, when and why a user or administrator changed the key or any other text that helps the user or administrator related to that key.

Don't depend on a comment in your program. A user is always allowed to remove or change it in any way they want to. But you are allowed or even encouraged to always show the content of the comment to the user and allow him to change it.

Parameters
keythe key object to work with
returnedCommentpre-allocated memory to copy the comments to
maxSizenumber of bytes that will fit returnedComment
Returns
the number of bytes actually copied to returnedString, including final NULL
Return values
1if the string is empty
-1on NULL pointer
-1if maxSize is 0, not enough to store the comment or when larger then SSIZE_MAX
See also
keyGetCommentSize(), keySetComment()

◆ keyGetCommentSize()

ssize_t keyGetCommentSize ( const Key *  key)

Calculates number of bytes needed to store a key comment, including final NULL.

Use this method to know to size for allocated memory to retrieve a key comment.

See keySetComment() for more information on comments.

For an empty key name you need one byte to store the ending NULL. For that reason 1 is returned.

char *buffer;
buffer = elektraMalloc (keyGetCommentSize (key));
// use this buffer to store the comment
// pass keyGetCommentSize (key) for maxSize
ssize_t keyGetCommentSize(const Key *key)
Calculates number of bytes needed to store a key comment, including final NULL.
Definition: meta.c:132
void * elektraMalloc(size_t size)
Allocate memory for Elektra.
Definition: internal.c:274
Parameters
keythe key object to work with
Returns
number of bytes needed
Return values
1if there is no comment
-1on NULL pointer
See also
keyGetComment(), keySetComment()

◆ keySetComment()

ssize_t keySetComment ( Key *  key,
const char *  newComment 
)

Set a comment for a key.

A key comment is like a configuration file comment. See keySetComment() for more information.

Parameters
keythe key object to work with
newCommentthe comment, that can be freed after this call.
Returns
the number of bytes actually saved including final NULL
Return values
0when the comment was freed (newComment NULL or empty string)
-1on NULL pointer or memory problems
See also
keyGetComment()