Enumerations | |
enum | KeyType { KEY_TYPE_UNDEFINED = 0, KEY_TYPE_DIR = 1, KEY_TYPE_LINK = 2, KEY_TYPE_BINARY = 20, KEY_TYPE_STRING = 40 } |
Key data types. More... | |
enum | KeyNamespace { KEY_NS_SYSTEM = 1, KEY_NS_USER = 2 } |
Elektra currently supported Key namespaces. More... | |
enum | KeySwitch { KEY_SWITCH_TYPE = 1, KEY_SWITCH_NAME = 1<<1, KEY_SWITCH_VALUE = 1<<2, KEY_SWITCH_OWNER = 1<<5, KEY_SWITCH_DOMAIN = KEY_SWITCH_OWNER, KEY_SWITCH_COMMENT = 1<<6, KEY_SWITCH_UID = 1<<7, KEY_SWITCH_GID = 1<<8, KEY_SWITCH_MODE = 1<<10, KEY_SWITCH_TIME = 1<<11, KEY_SWITCH_NEEDSYNC = 1<<12, KEY_SWITCH_ACTIVE = 1<<14, KEY_SWITCH_UMODE = 1<<15, KEY_SWITCH_ISSYSTEM = 1<<23, KEY_SWITCH_ISUSER = 1<<24, KEY_SWITCH_FLAG = 1<<31, KEY_SWITCH_END = 0, KEY_SWITCH_INITIALIZED = 0x10042008, KEY_SWITCH_INITMASK = 0x18442218 } |
Switches to denote the various Key attributes in methods throughout this library. More... | |
Functions | |
Key * | keyNew (const char *keyName,...) |
A practical way to fully create a Key object in one step. | |
int | keyDel (Key *key) |
A destructor for Key objects. | |
int | keyDup (const Key *source, Key *dest) |
Duplicate a key in memory. | |
int | keyInit (Key *key) |
Initializes the Key object with some default values. | |
int | keyClose (Key *key) |
Finishes the usage of a Key object. |
To use them:
#include <kdb.h>
A Key is the essential class that encapsulates key name , value and metainfo . Key properties are:
Described here the methods to allocate and free the key.
enum KeyType |
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 Color
, Font
, etc, you can still use it. You'll have to define a new type number in the scope of your application, and force the type with keySetType(), or keyNew().
The type number is a value between 0 and 255. If your user-defined type >= KEY_TYPE_STRING
, it will be still treated as a string (in the terms of Unicode handling). If KEY_TYPE_BINARY
<= type < KEY_TYPE_STRING
, Elektra will handle it as a binary value, will not make Unicode handling and will save it hex-encoded.
keySetType() for an example of how to define custom types
enum KeyNamespace |
Elektra currently supported Key namespaces.
enum KeySwitch |
Switches to denote the various Key attributes in methods throughout this library.
kdbMonitorKey(), kdbMonitorKeys(), the diffMask parameter
KEY_SWITCH_TYPE | Flag for the key type |
KEY_SWITCH_NAME | Flag for the key name |
KEY_SWITCH_VALUE | Flag for the key data |
KEY_SWITCH_OWNER | Flag for the key user domain |
KEY_SWITCH_DOMAIN | An alias |
KEY_SWITCH_COMMENT | Flag for the key comment |
KEY_SWITCH_UID | Flag for the key UID |
KEY_SWITCH_GID | Flag for the key GID |
KEY_SWITCH_MODE | Flag for the key permissions |
KEY_SWITCH_TIME | Flag for the key change time |
KEY_SWITCH_NEEDSYNC | Flags that key needs syncronization |
KEY_SWITCH_ACTIVE | |
KEY_SWITCH_UMODE | Flag for key permissions based on umask |
KEY_SWITCH_ISSYSTEM |
Flag to denote a "system" key |
KEY_SWITCH_ISUSER |
Flag to denote a "user" key |
KEY_SWITCH_FLAG | General purpose flag that has semantics only to your app |
KEY_SWITCH_END | Used as a parameter terminator to keyNew() |
KEY_SWITCH_INITIALIZED | |
KEY_SWITCH_INITMASK |
Key* keyNew | ( | const char * | keyName, | |
... | ||||
) |
A practical way to fully create a Key object in one step.
This function tries to mimic the C++ way for constructors.
Due to ABI compatibility, the Key
structure is not defined in kdb.h, only declared. So you can only declare pointers
to Keys
in your program, and allocate and free memory for them with keyNew() and keyDel() respectively. See http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html#AEN135
You can call it in many different ways depending on the attribute tags you pass as parameters. Tags are represented as the KeySwitch values, and tell keyNew() which Key attribute comes next.
The simplest and minimum way to use it is with no tags, only a key name:
Key *nullKey,*emptyNamedKey; // Create a key that has no name, is completely empty, but is initialized nullKey=keyNew(KEY_SWITCH_END); // Create and initialize a key with a name and nothing else emptyNamedKey=keyNew("user/some/example",KEY_SWITCH_END);
keyNew() allocates memory for a key object and then calls keyInit(). After that, it processes the given argument list.
The Key attribute tags are the following:
KeySwitch::KEY_SWITCH_GID
errno
. You will have to kdbOpen() before using keyNew() with this tag.keyName
is NULL too.
KeySet *ks=ksNew(); kdbOpen(); ksAppend(ks,keyNew(KEY_SWITCH_END)); // an empty key ksAppend(ks,keyNew("user/sw", // a simple key KEY_SWITCH_END)); // no more args ksAppend(ks,keyNew("system/sw", KEY_SWITCH_NEEDSYNC, handle, // a key retrieved from storage KEY_SWITCH_END)); // end of args ksAppend(ks,keyNew("user/tmp/ex1", KEY_SWITCH_VALUE,"some data", // with a simple value KEY_SWITCH_END)); // end of args ksAppend(ks,keyNew("user/tmp/ex2", KEY_SWITCH_VALUE,"some data", // with a simple value KEY_SWITCH_MODE,0777, // permissions KEY_SWITCH_END)); // end of args ksAppend(ks,keyNew("user/tmp/ex3", KEY_SWITCH_TYPE,KEY_TYPE_LINK, // only type KEY_SWITCH_VALUE,"system/mtp/x", // link destination KEY_SWITCH_MODE,0654, // weird permissions KEY_SWITCH_END)); // end of args ksAppend(ks,keyNew("user/tmp/ex4", KEY_SWITCH_TYPE,KEY_TYPE_BINARY, // key type KEY_SWITCH_VALUE,"some data",7, // value that will be truncated in 7 bytes KEY_SWITCH_COMMENT,"value is truncated", KEY_SWITCH_DOMAIN,"root", // owner (not uid) is root KEY_SWITCH_UID,0, // root uid KEY_SWITCH_END)); // end of args ksAppend(ks,keyNew("user/tmp/ex5", KEY_SWITCH_TYPE,KEY_TYPE_DIR, // dir key with... KEY_SWITCH_TYPE,KEY_TYPE_BINARY, // ...a binary value KEY_SWITCH_VALUE,"some data",7, // value that will be truncated in 7 bytes KEY_SWITCH_COMMENT,"value is truncated", KEY_SWITCH_DOMAIN,"root", // owner (not uid) is root KEY_SWITCH_UID,0, // root uid KEY_SWITCH_END)); // end of args ksAppend(ks,keyNew("user/env/alias/ls", // a key we know we have KEY_SWITCH_NEEDSYNC, handle, // retrieve from storage, passing the KDB handle KEY_SWITCH_END)); // do nothing more ksAppend(ks,keyNew("user/env/alias/ls", // same key KEY_SWITCH_NEEDSYNC, handle, // retrieve from storage KEY_SWITCH_DOMAIN,"root", // set new owner (not uid) as root KEY_SWITCH_COMMENT,"new comment", // set new comment KEY_SWITCH_END)); // end of args ksToStream(ks,stdout,KDB_O_XMLHEADERS); ksDel(ks); kdbClose();
keyName | a valid name to the key, or NULL to get a simple initialized, but really empty, object |
keyName
was passed (see keySetName()). Definition at line 373 of file key.c.
References kdbGetKey(), KEY_SWITCH_COMMENT, KEY_SWITCH_DOMAIN, KEY_SWITCH_FLAG, KEY_SWITCH_GID, KEY_SWITCH_MODE, KEY_SWITCH_NEEDSYNC, KEY_SWITCH_TYPE, KEY_SWITCH_UID, KEY_SWITCH_UMODE, KEY_SWITCH_VALUE, KEY_TYPE_BINARY, KEY_TYPE_DIR, KEY_TYPE_STRING, KEY_TYPE_UNDEFINED, keyInit(), keyIsDir(), keySetAccess(), keySetComment(), keySetDir(), keySetGID(), keySetName(), keySetOwner(), keySetRaw(), keySetString(), keySetType(), keySetUAccess(), and keySetUID().
Referenced by commandEdit(), commandGet(), commandList(), commandMonitor(), commandMove(), commandSet(), kdbGetChildKeys(), kdbGetRootKeys(), kdbGetValue(), kdbLink(), kdbMonitorKey_default(), kdbRemove(), kdbRename_default(), kdbSetValue(), and keyUnserialize().
int keyDel | ( | Key * | key | ) |
A destructor for Key objects.
Every key created by keyNew() must be deleted with keyDel(). It will keyClose() and free() the key
pointer.
There is the keyFree()
macro if you prefer this method name.
Definition at line 490 of file key.c.
References keyClose().
Referenced by commandEdit(), commandGet(), commandList(), commandMonitor(), commandMove(), commandSet(), kdbGetChildKeys(), kdbGetRootKeys(), kdbGetValue(), kdbLink(), kdbMonitorKey_default(), kdbRemove(), kdbRename_default(), kdbSetValue(), ksClose(), and ksCompare().
Duplicate a key in memory.
Both keys have to be initialized with keyInit(). If you have set any dynamic allocated memory for dest
, make sure that you keyClose() it before keyDup().
All private attributes of the source
key will be copied, including its context on a KeySet, and nothing will be shared between both keys.
Memory will be allocated as needed for dynamic properties as value, comment, etc.
source | has to be an initializised source Key | |
dest | will be the new copy of the Key |
Definition at line 2572 of file key.c.
References _Key::comment, _Key::data, _Key::dataSize, _Key::flags, _Key::key, KEY_SWITCH_NEEDSYNC, keySetComment(), keySetName(), keySetOwner(), keySetRaw(), and _Key::userDomain.
Referenced by kdbMonitorKey_default(), and kdbRename_default().
int keyInit | ( | Key * | key | ) |
Initializes the Key object with some default values.
This function should not be used by backends or applications, use keyNew() instead.
keyInit() sets the key to a clear state. It uses memset to clear the memory. The type of the key is KeyType::KEY_TYPE_UNDEFINED afterwards.
uid, gid and access masks are set with the current values of your system.
keyNew() and keyDel() are better ways to deal with initialization than keyInit() and keyClose()
keyNew() and keyDel() for construction and destruction of Keys
Definition at line 3173 of file key.c.
References _Key::flags, _Key::gid, KEY_SWITCH_INITIALIZED, KEY_TYPE_UNDEFINED, keySetUAccess(), _Key::type, and _Key::uid.
Referenced by keyNew().
int keyClose | ( | Key * | key | ) |
Finishes the usage of a Key object.
The key must be keyInit() before any attempt to close it.
Frees all internally allocated memory like value, comment, and leave the Key object ready to be keyInit()ed to reuse, or deallocated.
All internal states of the key will be NULL. After this process there is no information inside the key.
keyNew() and keyDel() are better ways to deal with initialization than keyInit() and keyClose()
keyNew() and keyDel() for construction and destruction of Keys
Definition at line 3218 of file key.c.
References _Key::comment, _Key::data, _Key::key, and _Key::userDomain.
Referenced by keyDel().