Elektra
0.8.8
|
Methods to do various tests on Keys. More...
Functions | |
int | keyCmp (const Key *k1, const Key *k2) |
int | keyNeedSync (const Key *key) |
int | keyIsSystem (const Key *key) |
int | keyIsUser (const Key *key) |
int | keyIsBelow (const Key *key, const Key *check) |
int | keyIsDirectBelow (const Key *key, const Key *check) |
int | keyRel (const Key *key, const Key *check) |
int | keyIsInactive (const Key *key) |
int | keyIsDir (const Key *key) |
int | keyIsBinary (const Key *key) |
int | keyIsString (const Key *key) |
keyswitch_t | keyCompare (const Key *key1, const Key *key2) |
Methods to do various tests on Keys.
To use them:
int keyCmp | ( | const Key * | k1, |
const Key * | k2 | ||
) |
Compare the name of two keys.
The comparison is based on a strcmp of the keynames, and iff they match a strcmp of the owner will be used to distuingish. If even this matches the keys are found to be exactly the same and 0 is returned. These two keys can't be used in the same KeySet.
keyCmp() defines the sorting order for a KeySet.
The following 3 points are the rules for null values:
If the name is equal then:
Often is enough to know if the other key is less then or greater then the other one. But Sometimes you need more precise information, see keyRel().
Given any Keys k1 and k2 constructed with keyNew(), following equation hold true:
Here are some more examples:
And even more:
Do not strcmp the keyName() yourself because the result differs from simple ascii comparison.
k1 | the first key object to compare with |
k2 | the second key object to compare with |
keyswitch_t keyCompare | ( | const Key * | key1, |
const Key * | key2 | ||
) |
Compare 2 keys.
The returned flags bit array has 1s (differ) or 0s (equal) for each key meta info compared, that can be logically ORed using keyswitch_t
flags. KEY_NAME , KEY_VALUE , KEY_OWNER , KEY_COMMENT , KEY_UID , KEY_GID , KEY_MODE and
key1 | first key |
key2 | second key |
int keyIsBelow | ( | const Key * | key, |
const Key * | check | ||
) |
Check if the key check is below the key key or not.
Example:
key user/sw/app check user/sw/app/key
returns true because check is below key
Example:
key user/sw/app check user/sw/app/folder/key
returns also true because check is indirect below key
key | the key object to work with |
check | the key to find the relative position of |
int keyIsBinary | ( | const Key * | key | ) |
Check if a key is binary type.
The function checks if the key is a binary. Opposed to string values binary values can have '\0' inside the value and may not be terminated by a null character. Their disadvantage is that you need to pass their size.
Make sure to use this function and don't test the binary type another way to ensure compatibility and to write less error prone programs.
key | the key to check |
int keyIsDir | ( | const Key * | key | ) |
Check if the mode for the key has access privileges.
In the filesys backend a key represented through a file has the mode 664, but a key represented through a folder 775. keyIsDir() checks if all 3 executeable bits are set.
If any executable bit is set it will be recognized as a directory.
To know if you can access the directory, you need to check, if your
Accessing does not mean that you can get any value or comments below, see Modes for more information.
key | the key object to work with |
int keyIsDirectBelow | ( | const Key * | key, |
const Key * | check | ||
) |
Check if the key check is direct below the key key or not.
Example: key user/sw/app check user/sw/app/key returns true because check is below key Example: key user/sw/app check user/sw/app/folder/key does not return true, because there is only a indirect relation
key | the key object to work with |
check | the key to find the relative position of |
int keyIsInactive | ( | const Key * | key | ) |
Check whether a key is inactive.
In Elektra terminology a hierarchy of keys is inactive if the rootkey's basename starts with '.'. So a key is also inactive if it is below an inactive key. For example, user/key/.hidden is inactive and so is user/.hidden/below.
Inactive keys should not have any meaning to applications, they are only a convention reserved for users and administrators. To automatically remove all inactive keys for an application, consider to use the hidden plugin.
key | the key object to work with |
1 | if the key is inactive |
0 | if the key is active |
-1 | on NULL pointer or when key has no name |
int keyIsString | ( | const Key * | key | ) |
Check if a key is string type.
String values are null terminated and are not allowed to have any '\0' characters inside the string.
Make sure to use this function and don't test the string type another way to ensure compatibility and to write less error prone programs.
key | the key to check |
int keyIsSystem | ( | const Key * | key | ) |
Check whether a key is under the system
namespace or not
key | the key object to work with |
system
, 0 otherwise int keyIsUser | ( | const Key * | key | ) |
Check whether a key is under the user
namespace or not.
key | the key object to work with |
user
, 0 otherwise int keyNeedSync | ( | const Key * | key | ) |
Test if a key needs to be synced to backend storage.
If any key modification took place the key will be flagged with KEY_FLAG_SYNC so that kdbSet() knows which keys were modified and which not.
After keyNew() the flag will normally be set, but after kdbGet() and kdbSet() the flag will be removed. When you modify the key the flag will be set again.
In your application you can make use of that flag to know if you changed something in a key after a kdbGet() or kdbSet().
key | the key object to work with |
key
was changed in memory, 0 otherwise int keyRel | ( | const Key * | key, |
const Key * | check | ||
) |
Information about the relation in the hierarchy between two keys.
Unlike keyCmp() the number gives information about hierarchical information.
user/key user/key
user/key/folder user/key/folder/child
user/key/folder user/key/folder/any/depth/deeper/grand-child
user/key/myself user/key/sibling
TODO Below is an idea how it could be extended: It could continue the search into the other direction if any (grand-)parents are equal.
user/key/myself user/key/sibling
user/key/myself user/key/sibling/nephew
user/key/myself user/key/sibling/any/depth/deeper/grand-nephew
The same holds true for the other direction, but with negative values. For no relation INT_MIN is returned.
key | the key object to work with |
check | the second key object to check the relation with |