$darkmode
Elektra 0.11.0
|
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... | |
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.
int elektraKeyCmpOrder | ( | const Key * | ka, |
const Key * | kb | ||
) |
Compare the order metadata of two keys.
ka | key to compare with |
kb | other key to compare with |
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 | the key the metadata should be added to |
metaName | the name of the metakey array parent |
value | the value of the newly appended metakey |
KeySet* elektraMetaArrayToKS | ( | Key * | key, |
const char * | metaName | ||
) |
Create a KeySet
from a metakey array.
For example, the following function call
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
key | the key containing the metakey array |
metaName | the name of the metakey array parent |
char* elektraMetaArrayToString | ( | const Key * | key, |
const char * | metaName, | ||
const char * | delim | ||
) |
returns the metakey array as a string separated by delim
key | the key containing the metakey array |
metaName | the name of the metakey array parent |
delim | delimiter for the records in the returned string |
int elektraSortTopology | ( | KeySet * | ks, |
Key ** | array | ||
) |
topological sorting
array | the array where the sorted keys will be stored in topological order. Nothing will be written into an array if |
ks | is the keyset that should be sorted. Dependencies and order is defined by metakeys. |
#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.
1 | on success |
0 | for cycles |
-1 | for invalid dependencies |
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
See keySetComment() for more information on comments.
key | the key object to work with |
"" | when there is no comment |
0 | on NULL pointer |
ssize_t keyGetComment | ( | const Key * | key, |
char * | returnedComment, | ||
size_t | maxSize | ||
) |
Get the key comment.
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.
key | the key object to work with |
returnedComment | pre-allocated memory to copy the comments to |
maxSize | number of bytes that will fit returnedComment |
returnedString
, including final NULL 1 | if the string is empty |
-1 | on NULL pointer |
-1 | if maxSize is 0, not enough to store the comment or when larger then SSIZE_MAX |
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.
key | the key object to work with |
1 | if there is no comment |
-1 | on NULL pointer |
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.
key | the key object to work with |
newComment | the comment, that can be freed after this call. |
0 | when the comment was freed (newComment NULL or empty string) |
-1 | on NULL pointer or memory problems |