Enumerations | |
enum | KeyType { KEY_TYPE_UNDEFINED = 0, KEY_TYPE_DIR = 1, KEY_TYPE_LINK = 2, KEY_TYPE_BINARY = 20, KEY_TYPE_STRING = 40 } |
enum | KeyNamespace { KEY_NS_SYSTEM = 1, KEY_NS_USER = 2 } |
enum | KeyFlags { , KEY_FLAG_HASTYPE = 1, KEY_FLAG_HASKEY = 1<<1, KEY_FLAG_HASDATA = 1<<2, KEY_FLAG_HASDOMAIN = 1<<5, KEY_FLAG_HASCOMMENT = 1<<6, KEY_FLAG_HASUID = 1<<7, KEY_FLAG_HASGID = 1<<8, KEY_FLAG_HASPRM = 1<<10, KEY_FLAG_HASTIME = 1<<11, KEY_FLAG_NEEDSYNC = 1<<12 , KEY_FLAG_FLAG = 1<<31 } |
Functions | |
int | keyInit (Key *key) |
int | keyClose (Key *key) |
int | keyIsInitialized (const Key *key) |
int | keyNeedsSync (const Key *key) |
u_int8_t | keyGetType (const Key *key) |
u_int8_t | keySetType (Key *key, u_int8_t newType) |
size_t | keyGetDataSize (const Key *key) |
size_t | keyGetNameSize (const Key *key) |
size_t | keyGetFullNameSize (const Key *key) |
size_t | keyGetFullName (const Key *key, char *returnedName, size_t maxSize) |
size_t | keyGetName (const Key *key, char *returnedName, size_t maxSize) |
size_t | keySetName (Key *key, const char *newName) |
size_t | keyGetOwner (const Key *key, char *returned, size_t maxSize) |
size_t | keyGetOwnerSize (const Key *key) |
size_t | keySetOwner (Key *key, const char *userDomain) |
size_t | keyGetComment (const Key *key, char *returnedDesc, size_t maxSize) |
size_t | keySetComment (Key *key, const char *newComment) |
size_t | keyGetCommentSize (const Key *key) |
size_t | keyGetString (const Key *key, char *returnedString, size_t maxSize) |
size_t | keySetString (Key *key, const char *newString) |
size_t | keyGetBinary (const Key *key, void *returnedBinary, size_t maxSize) |
size_t | keySetBinary (Key *key, const void *newBinary, size_t dataSize) |
size_t | keySetRaw (Key *key, const void *newBinary, size_t dataSize) |
size_t | keyGetLink (const Key *key, char *returnedTarget, size_t maxSize) |
int | keyDup (const Key *source, Key *dest) |
uid_t | keyGetUID (const Key *key) |
int | keySetUID (Key *key, uid_t uid) |
gid_t | keyGetGID (const Key *key) |
int | keySetGID (Key *key, gid_t gid) |
mode_t | keyGetAccess (const Key *key) |
int | keySetAccess (Key *key, mode_t mode) |
time_t | keyGetMTime (const Key *key) |
time_t | keyGetATime (const Key *key) |
time_t | keyGetCTime (const Key *key) |
size_t | keyGetParentSize (const Key *key) |
size_t | keyGetParent (const Key *key, char *returnedParent, size_t maxSize) |
u_int32_t | keyCompare (const Key *key1, const Key *key2) |
size_t | keyToStream (const Key *key, FILE *stream, unsigned long options) |
int | keyNameIsSystem (const char *keyName) |
int | keyNameIsUser (const char *keyName) |
int | keyIsSystem (const Key *key) |
int | keyIsUser (const Key *key) |
int | keyNameGetNamespace (const char *keyName) |
int | keyGetNamespace (const Key *key) |
int | keyIsDir (const Key *key) |
int | keyIsLink (const Key *key) |
size_t | keyNameGetRootNameSize (const char *keyName) |
size_t | keyGetRootNameSize (const Key *key) |
size_t | keyGetFullRootNameSize (const Key *key) |
size_t | keyNameGetBaseNameSize (const char *keyName) |
size_t | keyGetBaseNameSize (const Key *key) |
size_t | keyGetRootName (const Key *key, char *returned, size_t maxSize) |
size_t | keyGetFullRootName (const Key *key, char *returned, size_t maxSize) |
size_t | keyGetBaseName (const Key *key, char *returned, size_t maxSize) |
int | keySetFlag (Key *key) |
int | keyClearFlag (Key *key) |
int | keyGetFlag (const Key *key) |
To use it:
#include <kdb.h>
A Key is the essential class that contains all key data and metadata. Key properties are:
Rules for Key Names
When using Elektra to store your application's configuration and state, please keep in mind the following rules:
system
or user
.system
or user
. They are reserved for very essential OS subsystems.system/sw/MyApp
and/or user/sw/MyApp
.system/sw/MyApp/current
and/or user/sw/MyApp/current
. This way, from a sysadmin perspective, it will be possible to copy the system/sw/MyApp/current
tree to something like system/sw/MyApp/old
, and keep system clean and organized.Described here the methods to get and set, and make various manipulations in the objects of class Key.
|
Flags that can be used with keys.
|
|
Elektra currently supported Key namespaces. |
|
Key data types. Key type values grow from the semantically poor to the semantically rich. The gaps between them is for user-defined types.
If your application needs value types with more semantics, like
The type number is a value between 0 and 255. If you define it bigger than
|
|
Clear the general flag in the Key The flag has no semantics to the library, only to your application.
Definition at line 2165 of file key.c. References KDB_RET_UNINITIALIZED, KEY_FLAG_FLAG, and keyIsInitialized(). |
|
Finishes the usage of a Key object. Frees all internally allocated memory, and leave the Key object ready to be destroyed, or explicitly by a free(), or a local variable dealocation.
Definition at line 149 of file key.c. References KDB_RET_NULLKEY, and keyIsInitialized(). Referenced by commandEdit(), commandList(), kdbGetChildKeys(), kdbGetValue(), kdbLink(), kdbMonitorKey(), kdbRemove(), kdbSetKey(), kdbSetValue(), keyDup(), ksClose(), and ksCompare(). |
|
Compare 2 keys.
The returned flag array has 1s (different) or 0s (same) for each key meta info compared, that can be logically ORed with
Definition at line 1372 of file key.c. References KEY_FLAG_HASCOMMENT, KEY_FLAG_HASDATA, KEY_FLAG_HASDOMAIN, KEY_FLAG_HASGID, KEY_FLAG_HASKEY, KEY_FLAG_HASPRM, KEY_FLAG_HASTYPE, and KEY_FLAG_HASUID. Referenced by kdbMonitorKey(), and ksCompare(). |
|
Clone a key. All private information of the source key will be copied, and nothing will be shared between both keys. keyClose() will be used on destination key before the operation. Internal buffers will be automatically allocated on destination.
Definition at line 1103 of file key.c. References keyClose(), keySetComment(), keySetName(), keySetOwner(), and keySetRaw(). Referenced by kdbMonitorKey(). |
|
Return the key filesystem-like access permissions.
Definition at line 1221 of file key.c. References KDB_RET_UNINITIALIZED, and keyIsInitialized(). Referenced by kdbSetKey(), and keyToStream(). |
|
Get last time the key data was read from disk. Definition at line 1273 of file key.c. References KDB_RET_UNINITIALIZED, and keyIsInitialized(). |
|
Calculate the basename of a key name and put it in Some examples:
Definition at line 2102 of file key.c. References KDB_RET_NOKEY, KDB_RET_NULLKEY, KDB_RET_TRUNC, KDB_RET_UNINITIALIZED, keyGetBaseNameSize(), and keyIsInitialized(). Referenced by commandGet(). |
|
Calculates number of bytes needed to store basename of a key. Basenames are denoted as:
Definition at line 1975 of file key.c. References keyIsInitialized(), and keyNameGetBaseNameSize(). Referenced by commandGet(), and keyGetBaseName(). |
|
Get the value of a binary or string key.
Definition at line 953 of file key.c. References KDB_RET_NODATA, KDB_RET_TRUNC, KDB_RET_UNINITIALIZED, and keyIsInitialized(). Referenced by commandGet(). |
|
Get the key comment. A Key comment is pretty much as a comment in a text configuration file.
Definition at line 702 of file key.c. References KDB_RET_NODESC, KDB_RET_TRUNC, KDB_RET_UNINITIALIZED, and keyIsInitialized(). Referenced by commandGet(). |
|
Calculates number of bytes needed to store a key comment, including final NULL. Use this method to allocate memory to retrieve a key comment.
Definition at line 775 of file key.c. References KDB_RET_NODESC, KDB_RET_UNINITIALIZED, and keyIsInitialized(). Referenced by commandGet(). |
|
Get last time the key was stated from disk. Definition at line 1287 of file key.c. References KDB_RET_UNINITIALIZED, and keyIsInitialized(). |
|
Returns the number of bytes of the key value This method is used with malloc() before a keyGetString() or keyGetBinary().
Definition at line 314 of file key.c. References KDB_RET_UNINITIALIZED, and keyIsInitialized(). Referenced by commandGet(), and commandMonitor(). |
|
Get the flag from the Key. The flag has no semantics to the library, only to your application.
Definition at line 2190 of file key.c. References KDB_RET_UNINITIALIZED, KEY_FLAG_FLAG, and keyIsInitialized(). |
|
Get key full name, including the user domain name.
Definition at line 391 of file key.c. References KDB_RET_TRUNC, and keyGetFullNameSize(). Referenced by commandEdit(), commandGet(), commandImport(), commandList(), kdbGetChildKeys(), kdbGetKeyByParentKey(), and keyToStream(). |
|
Space needed to store the key name including user domain
Definition at line 363 of file key.c. References KDB_RET_UNINITIALIZED, and keyIsInitialized(). Referenced by commandGet(), kdbGetChildKeys(), kdbGetKeyByParentKey(), and keyGetFullName(). |
|
Copy to Some examples:
This method is more robust then keyGetRootName()
Definition at line 2048 of file key.c. References KDB_RET_NOKEY, KDB_RET_TRUNC, KDB_RET_UNINITIALIZED, keyGetFullRootNameSize(), keyGetRootNameSize(), keyIsInitialized(), and keyIsUser(). |
|
Calculates number of bytes needed to store full root name of a key.
Possible root key names are
Definition at line 1906 of file key.c. References keyIsUser(), and keyNameGetRootNameSize(). Referenced by keyGetFullRootName(). |
|
Get the system's group ID of a key
Definition at line 1185 of file key.c. References KDB_RET_UNINITIALIZED, and keyIsInitialized(). Referenced by kdbSetKey(), and keyToStream(). |
|
Definition at line 1046 of file key.c. References KDB_RET_NODATA, KDB_RET_TRUNC, KDB_RET_TYPEMISMATCH, KDB_RET_UNINITIALIZED, KEY_TYPE_LINK, and keyIsInitialized(). Referenced by kdbSetKey(). |
|
Get last modification time of the key on disk. Definition at line 1258 of file key.c. References KDB_RET_UNINITIALIZED, and keyIsInitialized(). |
|
Get abreviated key name (without user domain name)
Definition at line 430 of file key.c. References KDB_RET_NOKEY, KDB_RET_TRUNC, KDB_RET_UNINITIALIZED, and keyIsInitialized(). Referenced by commandGet(). |
|
Space needed to store the key name without user domain
Definition at line 343 of file key.c. References KDB_RET_UNINITIALIZED, and keyIsInitialized(). Referenced by commandGet(), and kdbMonitorKey(). |
|
Return the namespace of a key Currently valid namespaces are KEY_NS_SYSTEM and KEY_NS_USER.
Definition at line 1796 of file key.c. References keyIsInitialized(), and keyNameGetNamespace(). |
|
Return the user domain of the key.
Only Although usually the same, the user domain of a key is not related to its UID. User domains are related to WHERE the key is stored on disk, while UIDs are related to access controls of a key.
Definition at line 606 of file key.c. References KDB_RET_NODOMAIN, KDB_RET_TRUNC, KDB_RET_UNINITIALIZED, and keyIsInitialized(). |
|
Return the size of the user domain of the Key.
Definition at line 632 of file key.c. References KDB_RET_NODOMAIN, KDB_RET_UNINITIALIZED, and keyIsInitialized(). |
|
Copy this key's parent name into a pre-allocated buffer.
Definition at line 1347 of file key.c. References KDB_RET_TRUNC, and keyGetParentSize(). |
|
Get the number of bytes needed to store this key's parent name.
Definition at line 1303 of file key.c. References KDB_RET_NOKEY, KDB_RET_UNINITIALIZED, and keyIsInitialized(). Referenced by keyGetParent(). |
|
Copy to Some examples:
Use keyGetFullRootName() to get also the user domain.
Definition at line 2004 of file key.c. References KDB_RET_NOKEY, KDB_RET_TRUNC, KDB_RET_UNINITIALIZED, keyGetRootNameSize(), and keyIsInitialized(). |
|
Gets number of bytes needed to store root name of a key.
Possible root key names are
Definition at line 1883 of file key.c. References keyIsInitialized(), and keyNameGetRootNameSize(). Referenced by keyGetFullRootName(), and keyGetRootName(). |
|
Get the value of a key as a string. If the value can't be represented as a text string (binary value), errno is set to KDB_RET_TYPEMISMATCH.
Definition at line 891 of file key.c. References KDB_RET_NODATA, KDB_RET_TRUNC, KDB_RET_TYPEMISMATCH, KDB_RET_UNINITIALIZED, KEY_TYPE_STRING, and keyIsInitialized(). Referenced by commandGet(), commandMonitor(), and kdbGetValue(). |
|
Returns the key data type.
Definition at line 205 of file key.c. References KDB_RET_UNINITIALIZED, KEY_TYPE_UNDEFINED, and keyIsInitialized(). Referenced by commandGet(), commandSet(), and keyToStream(). |
|
Get the user ID of a key Although usually the same, the UID of a key is not related to its user domain.
Definition at line 1141 of file key.c. References KDB_RET_UNINITIALIZED, and keyIsInitialized(). Referenced by kdbSetKey(), and keyToStream(). |
|
Initializes a Key object. Every Key object that will be used must be initialized first, to setup pointers, counters, etc.
Definition at line 123 of file key.c. References KDB_RET_NULLKEY, and KEY_TYPE_UNDEFINED. Referenced by commandEdit(), commandGet(), commandList(), commandMonitor(), commandSet(), kdbGetChildKeys(), kdbGetRootKeys(), kdbGetValue(), kdbLink(), kdbMonitorKey(), kdbRemove(), kdbRename(), kdbSetKey(), keySetAccess(), keySetComment(), keySetGID(), keySetName(), keySetOwner(), keySetRaw(), keySetType(), and keySetUID(). |
|
Check if a key is folder key Folder keys have no value.
Definition at line 1813 of file key.c. References KEY_TYPE_DIR, and keyIsInitialized(). Referenced by kdbGetKey(), and kdbSetKey(). |
|
Test if a Key object is initialized. It is more or less reliable. You'd better guarantee your code is robust enough using keyInit() and keyClose() everytime.
Definition at line 176 of file key.c. Referenced by keyClearFlag(), keyClose(), keyGetAccess(), keyGetATime(), keyGetBaseName(), keyGetBaseNameSize(), keyGetBinary(), keyGetComment(), keyGetCommentSize(), keyGetCTime(), keyGetDataSize(), keyGetFlag(), keyGetFullNameSize(), keyGetFullRootName(), keyGetGID(), keyGetLink(), keyGetMTime(), keyGetName(), keyGetNameSize(), keyGetNamespace(), keyGetOwner(), keyGetOwnerSize(), keyGetParentSize(), keyGetRootName(), keyGetRootNameSize(), keyGetString(), keyGetType(), keyGetUID(), keyIsDir(), keyIsLink(), keyIsSystem(), keyIsUser(), keySetAccess(), keySetComment(), keySetFlag(), keySetGID(), keySetName(), keySetOwner(), keySetRaw(), keySetType(), keySetUID(), and keyToStream(). |
|
Check if a key is a link key The value of link keys is the key they point to.
Definition at line 1830 of file key.c. References KEY_TYPE_LINK, and keyIsInitialized(). Referenced by kdbGetChildKeys(), kdbSetKey(), and kdbStatKey(). |
|
Check whether a key is under the
Definition at line 1736 of file key.c. References keyIsInitialized(), and keyNameIsSystem(). |
|
Check whether a key is under the
Definition at line 1754 of file key.c. References keyIsInitialized(), and keyNameIsUser(). Referenced by keyGetFullRootName(), and keyGetFullRootNameSize(). |
|
Calculates number of bytes needed to store basename of a key name. Basenames are denoted as:
Definition at line 1929 of file key.c. References keyNameGetRootNameSize(). Referenced by keyGetBaseNameSize(). |
|
Return the namespace of a key name Currently valid namespaces are KEY_NS_SYSTEM and KEY_NS_USER.
Definition at line 1776 of file key.c. References KEY_NS_SYSTEM, KEY_NS_USER, keyNameIsSystem(), and keyNameIsUser(). Referenced by keyGetNamespace(). |
|
Gets number of bytes needed to store root name of a key name
Possible root key names are
Definition at line 1847 of file key.c. Referenced by keyGetFullRootNameSize(), keyGetRootNameSize(), keyNameGetBaseNameSize(), and keySetName(). |
|
Check whether a key name is under the
Definition at line 1698 of file key.c. Referenced by keyIsSystem(), and keyNameGetNamespace(). |
|
Check whether a key name is under the
Definition at line 1717 of file key.c. Referenced by keyIsUser(), and keyNameGetNamespace(). |
|
Test if an in-memory Key object was changed after retrieved from disk. All Key methods that change objects properties will set an internal flag, that is checked by this method.
Definition at line 190 of file key.c. References KEY_FLAG_NEEDSYNC. Referenced by kdbSetKeys(). |
|
Set the key filesystem-like access permissions.
Definition at line 1241 of file key.c. References KDB_RET_UNINITIALIZED, KEY_FLAG_HASPRM, KEY_FLAG_NEEDSYNC, keyInit(), and keyIsInitialized(). Referenced by commandSet(). |
|
Set the value of a key as a binary. On disk, value will be encoded into a human readable hex-digit text format and no UTF-8 encoding will be applied. UNIX sysadmins don't like to deal with binary, sand box data. Consider using a string key instead.
Definition at line 990 of file key.c. References KEY_TYPE_BINARY, keySetRaw(), and keySetType(). Referenced by commandSet(). |
|
Set a comment for a key. A key comment is like a configuration file comment. It has no size limit. A private copy will be stored.
Definition at line 735 of file key.c. References KDB_RET_UNINITIALIZED, KEY_FLAG_HASCOMMENT, KEY_FLAG_NEEDSYNC, keyInit(), and keyIsInitialized(). Referenced by commandSet(), and keyDup(). |
|
Set a general flag in the Key The flag has no semantics to the library, only to your application.
Definition at line 2143 of file key.c. References KDB_RET_UNINITIALIZED, KEY_FLAG_FLAG, and keyIsInitialized(). |
|
Set the system's group ID of a key
Definition at line 1205 of file key.c. References KDB_RET_UNINITIALIZED, KEY_FLAG_HASGID, KEY_FLAG_NEEDSYNC, keyInit(), and keyIsInitialized(). Referenced by commandSet(). |
|
Set a new name to a key. A valid name is of the form:
The last form has explicitly set the user domain, to let the library know in which user folder to save the key. A user domain is a user name. If not defined (the second form) current user is calculated and used as default. A private copy of the key name will be stored, and the
Definition at line 477 of file key.c. References KDB_RET_INVALIDKEY, KDB_RET_UNINITIALIZED, KEY_FLAG_HASKEY, KEY_FLAG_NEEDSYNC, keyInit(), keyIsInitialized(), and keyNameGetRootNameSize(). Referenced by commandEdit(), commandGet(), commandList(), commandMonitor(), commandSet(), kdbGetChildKeys(), kdbGetKeyByParent(), kdbGetKeyByParentKey(), kdbGetRootKeys(), kdbGetValue(), kdbLink(), kdbRemove(), kdbRename(), kdbSetKey(), kdbSetValue(), and keyDup(). |
|
Set the user domain of a key. A user domain is a user name. A private copy is stored, so the passed parameter can be freed after the call.
Definition at line 660 of file key.c. References KDB_RET_UNINITIALIZED, KEY_FLAG_HASDOMAIN, KEY_FLAG_NEEDSYNC, keyInit(), and keyIsInitialized(). Referenced by keyDup(). |
|
Set raw data as the value of a key. If NULL pointers are passed, key value is cleaned. This method will not change or set the key type, and should not be used unless working with user-defined value types.
Definition at line 1013 of file key.c. References KDB_RET_UNINITIALIZED, KEY_FLAG_HASDATA, KEY_FLAG_NEEDSYNC, keyInit(), and keyIsInitialized(). Referenced by keyDup(), keySetBinary(), keySetString(), and keySetType(). |
|
Set the value of a key as a string. On disk, text will be encoded to UTF-8.
Definition at line 930 of file key.c. References KEY_TYPE_STRING, keySetRaw(), and keySetType(). Referenced by commandSet(), and kdbSetValue(). |
|
Force a key type. This method is usually not needed, unless you are working with more semantic key types, or want to force a specific type for a key. It is not usually needed because the data type is automatically set when setting the key value.
The
Definition at line 278 of file key.c. References KDB_RET_UNINITIALIZED, KEY_FLAG_NEEDSYNC, KEY_TYPE_DIR, KEY_TYPE_UNDEFINED, keyInit(), keyIsInitialized(), and keySetRaw(). Referenced by commandSet(), keySetBinary(), and keySetString(). |
|
Set the user ID of a key. Although usually the same, the UID of a key is not related to its user domain.
Definition at line 1166 of file key.c. References KDB_RET_UNINITIALIZED, KEY_FLAG_HASUID, KEY_FLAG_NEEDSYNC, keyInit(), and keyIsInitialized(). Referenced by commandSet(). |
|
Prints an XML representation of the key. String generated is of the form: <key id="123445" uid="root" gid="root" mode="0660" atime="123456" ctime="123456" mtime="123456" name="system/sw/XFree/Monitor/Monitor0/Name" type="string"> <value>Samsung TFT panel</value> <comment>My monitor</comment> </key> Accepted options that can be ORed:
Definition at line 1445 of file key.c. References KDB_O_CONDENSED, KDB_O_NUMBERS, KDB_RET_UNINITIALIZED, KEY_TYPE_BINARY, KEY_TYPE_DIR, KEY_TYPE_LINK, KEY_TYPE_STRING, keyGetAccess(), keyGetFullName(), keyGetGID(), keyGetType(), keyGetUID(), and keyIsInitialized(). Referenced by commandList(), and ksToStream(). |