Elektra
0.8.12
|
Meta data proposal+compatibility methods. More...
Functions | |
const char * | keyOwner (const Key *key) |
Return a pointer to the real internal key owner. | |
ssize_t | keyGetOwnerSize (const Key *key) |
Return the size of the owner of the Key with concluding 0. | |
ssize_t | keyGetOwner (const Key *key, char *returnedOwner, size_t maxSize) |
Return the owner of the key. | |
ssize_t | keySetOwner (Key *key, const char *newOwner) |
Set the owner of a key. | |
const char * | keyComment (const Key *key) |
Return a pointer to the real internal key comment. | |
ssize_t | keyGetCommentSize (const Key *key) |
Calculates number of bytes needed to store a key comment, including final NULL. | |
ssize_t | keyGetComment (const Key *key, char *returnedComment, size_t maxSize) |
Get the key comment. | |
ssize_t | keySetComment (Key *key, const char *newComment) |
Set a comment for a key. | |
uid_t | keyGetUID (const Key *key) |
Get the user ID of a key. | |
int | keySetUID (Key *key, uid_t uid) |
Set the user ID of a key. | |
gid_t | keyGetGID (const Key *key) |
Get the group ID of a key. | |
int | keySetGID (Key *key, gid_t gid) |
Set the group ID of a key. | |
int | keySetDir (Key *key) |
Set mode so that key will be recognized as directory. | |
mode_t | keyGetMode (const Key *key) |
Return the key mode permissions. | |
int | keySetMode (Key *key, mode_t mode) |
Set the key mode permissions. | |
time_t | keyGetATime (const Key *key) |
Get last time the key data was read from disk. | |
int | keySetATime (Key *key, time_t atime) |
Update the atime information for a key. | |
time_t | keyGetMTime (const Key *key) |
Get last modification time of the key on disk. | |
int | keySetMTime (Key *key, time_t mtime) |
Update the mtime information for a key. | |
time_t | keyGetCTime (const Key *key) |
Get last time the key metadata was changed from disk. | |
int | keySetCTime (Key *key, time_t ctime) |
Update the ctime information for a key. | |
int | elektraKeyCmpOrder (const Key *ka, const Key *kb) |
Compare the order metadata of two keys. | |
Meta data proposal+compatibility methods.
In versions before Elektra 0.8 only meta data as listed here was available. Now any meta data can be added. These API methods are implementations of the 0.7 API using 0.8 meta data.
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 |
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 |
time_t keyGetATime | ( | const Key * | key | ) |
Get last time the key data was read from disk.
Every kdbGet() might update the access time of a key. You get information when the key was read the last time from the database.
You will get 0 when the key was not read already.
Beware that multiple copies of keys with keyDup() might have different atimes because you kdbGet() one, but not the other. You can use this information to decide which key is the latest.
key | Key to get information from. |
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 he wants 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 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 |
time_t keyGetCTime | ( | const Key * | key | ) |
Get last time the key metadata was changed from disk.
You will get 0 when the key was not read already.
Any changed field in metadata will influence the ctime of a key.
This time is not updated if only value or comment are changed.
Not changed keys will not update this time, even after kdbSet().
It is possible that other keys written to disc influence this time if the backend is not grained enough.
key | Key to get information from. |
gid_t keyGetGID | ( | const Key * | key | ) |
Get the group ID of a key.
The group ID is a unique identification for every group present on a system. Keys will belong to root (0) as long as you did not get their real GID with kdbGet().
Unlike UID users might change their group. This makes it possible to share configuration between some users.
A fresh key will have (gid_t)-1 also known as the group nogroup. It means that the key is not related to a group ID at the moment.
key | the key object to work with |
mode_t keyGetMode | ( | const Key * | key | ) |
Return the key mode permissions.
Default is 0664 (octal) for keys and 0775 for directory keys which used keySetDir().
The defaults are defined with the macros KDB_FILE_MODE and KDB_DIR_MODE.
For more information about the mode permissions see Modes.
key | the key object to work with |
time_t keyGetMTime | ( | const Key * | key | ) |
Get last modification time of the key on disk.
You will get 0 when the key was not read already.
Everytime you change value or comment and kdbSet() the key the mtime will be updated. When you kdbGet() the key, the atime is set appropriate.
Not changed keys may not even passed to kdbSet_backend() so it will not update this time, even after kdbSet().
It is possible that other keys written to disc influence this time if the backend is not grained enough.
If you add or remove a key the key thereunder in the hierarchy will update the mtime if written with kdbSet() to disc.
key | Key to get information from. |
ssize_t keyGetOwner | ( | const Key * | key, |
char * | returnedOwner, | ||
size_t | maxSize | ||
) |
Return the owner of the key.
user:someuser/
..... return someuser
user:some.user/
.... return some.user
user/
.... return the current userOnly user/
... keys have a owner. For system/
... keys (that doesn't have a key owner) an empty string ("") is returned.
Although usually the same, the owner of a key is not related to its UID. Owner are related to WHERE the key is stored on disk, while UIDs are related to mode controls of a key.
key | the object to work with |
returnedOwner | a pre-allocated space to store the owner |
maxSize | maximum number of bytes that fit returned |
ssize_t keyGetOwnerSize | ( | const Key * | key | ) |
Return the size of the owner of the Key with concluding 0.
The returned number can be used to allocate a string. 1 will returned on an empty owner to store the concluding 0 on using keyGetOwner().
key | the key object to work with |
uid_t keyGetUID | ( | const Key * | key | ) |
Get the user ID of a key.
The user ID is a unique identification for every user present on a system. Keys will belong to root (0) as long as you did not get their real UID with kdbGet().
Although usually the same, the UID of a key is not related to its owner.
A fresh key will have no UID.
key | the key object to work with |
const char* keyOwner | ( | const Key * | key | ) |
Return a pointer to the real internal key
owner.
This is a much more efficient version of keyGetOwner() and you should use it if you are responsible enough to not mess up things. You are not allowed to modify the returned string in any way. If you need a copy of the string, consider to use keyGetOwner() instead.
keyOwner() returns "" when there is no keyOwner. The reason is
key | the key object to work with |
"" | when there is no (a empty) owner |
0 | iff key is a NULL pointer |
int keySetATime | ( | Key * | key, |
time_t | atime | ||
) |
Update the atime information for a key.
When you do manual sync of keys you might also update the atime to make them indistinguishable.
It can also be useful if you work with keys not using a keydatabase.
key | The Key object to work with |
atime | The new access time for the key |
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. |
int keySetCTime | ( | Key * | key, |
time_t | ctime | ||
) |
Update the ctime information for a key.
key | The Key object to work with |
ctime | The new change metadata time for the key |
int keySetDir | ( | Key * | key | ) |
Set mode so that key will be recognized as directory.
The function will add all executable bits.
The macro KDB_DIR_MODE (defined to 0111) will be used for that.
The executable bits show that child keys are allowed and listable. There is no way to have child keys which are not listable for anyone, but it is possible to restrict listing the keys to the owner only.
For more about mode see keySetMode().
It is not possible to access keys below a not executable key. If a key is not writeable and executable kdbSet() will fail to access the keys below. If a key is not readable and executable kdbGet() will fail to access the keys below.
key | the key to set permissions to be recognized as directory. |
int keySetGID | ( | Key * | key, |
gid_t | gid | ||
) |
Set the group ID of a key.
See GID for more information about group IDs.
key | the key object to work with |
gid | is the group ID |
int keySetMode | ( | Key * | key, |
mode_t | mode | ||
) |
Set the key mode permissions.
The mode consists of 9 individual bits for mode permissions. In the following explanation the octal notation with leading zero will be used.
Default is 0664 (octal) for keys and 0775 for directory keys which used keySetDir().
The defaults are defined with the macros KDB_FILE_MODE and KDB_DIR_MODE.
0000 is the most restrictive mode. No user might read, write or execute the key.
Reading the key means to get the value by kdbGet().
Writing the key means to set the value by kdbSet().
Execute the key means to make a step deeper in the hierarchy. But you must be able to read the key to be able to list the keys below. See also keySetDir() in that context. But you must be able to write the key to be able to add or remove keys below.
0777 is the most relaxing mode. Every user is allowed to read, write and execute the key, if he is allowed to execute and read all keys below.
0700 allows every action for the current user, identified by the uid. See keyGetUID() and keySetUID().
To be more specific for the user the single bits can elect the mode for read, write and execute. 0100 only allows executing which gives the information that it is a directory for that user, but not accessable. 0200 only allows reading. This information may be combined to 0300, which allows execute and reading of the directory. Last 0400 decides about the writing permissions.
The same as above is also valid for the 2 other octal digits. 0070 decides about the group permissions, in that case full access. Groups are identified by the gid. See keyGetGID() and keySetGID(). In that example everyone with a different uid, but the gid of the the key, has full access.
0007 decides about the world permissions. This is taken into account when neighter the uid nor the gid matches. So that example would allow everyone with a different uid and gid of that key gains full access.
key | the key to set mode permissions |
mode | the mode permissions |
int keySetMTime | ( | Key * | key, |
time_t | mtime | ||
) |
Update the mtime information for a key.
key | The Key object to work with |
mtime | The new modification time for the key |
ssize_t keySetOwner | ( | Key * | key, |
const char * | newOwner | ||
) |
Set the owner of a key.
A owner is a name of a system user related to a UID. The owner decides on which location on the disc the key goes.
A private copy is stored, so the passed parameter can be freed after the call.
key | the key object to work with |
newOwner | the string which describes the owner of the key |
int keySetUID | ( | Key * | key, |
uid_t | uid | ||
) |
Set the user ID of a key.
See UID for more information about user IDs.
key | the key object to work with |
uid | the user ID to set |