Key :: Basic Methods

Key construction and initialization methods. More...

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_ISSYSTEM = 1<<23,   KEY_SWITCH_ISUSER = 1<<24,   KEY_SWITCH_FLAG = 1<<31,   KEY_SWITCH_END = 0 }
	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 memory of keys.
int	keyInit (Key *key)
	Initializes the Key object with some default values.
int	keyClose (Key *key)
	Finishes the usage of a Key object.

---

Detailed Description

Key construction and initialization methods.

To use them:

#include <kdb.h>

A Key is the essential class that encapsulates key name , value and metainfo . Key properties are:

• Key name
• Key value
• Data type
• Key comment
• User domain (the user that owns the key)
• UID, GID and filesystem-like access permissions
• Access, change and modification times
• A general flag

Described here the methods to allocate and free the key.

---

Enumeration Type Documentation

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. See also: keyGetType() keySetType() for an example of how to define custom types Enumeration values: KEY_TYPE_UNDEFINED  Undefined key type KEY_TYPE_DIR  A directory key KEY_TYPE_LINK  A symbolink link key. This gap is for special key meta types, that can't go into regular files. KEY_TYPE_BINARY  A binary key. This gap is for binary data types that have some semantics that somebody can invent in the future KEY_TYPE_STRING  A string key Definition at line 90 of file kdb.h.

enum KeyNamespace

Elektra currently supported Key namespaces. See also: kdbGetRootKeys(), keyGetNamespace(), keyNameGetNamespace() Enumeration values: KEY_NS_SYSTEM  The system keys KEY_NS_USER  The user keys Definition at line 113 of file kdb.h.

enum KeySwitch

Switches to denote the various Key attributes in methods throughout this library. See also: keyNew() keyCompare() kdbMonitorKey(), kdbMonitorKeys(), the diffMask parameter keyGetFlag(), keySetFlag() Enumeration values: 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_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() Definition at line 153 of file kdb.h.

---

Function Documentation

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 way to call it is with no tags, only a key name. See example bellow. 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_TYPE This tag requires 1 or 2 more parameters. The first is obviously the type. If the type is KeySwitch::KEY_TYPE_BINARY or any other binary-like user-defined type (see keySetType()), a second parameter is needed and is the size in bytes (size_t) of the data passed on the subsequent KeySwitch::KEY_SWITCH_VALUE parameter. You must use this tag before KeySwitch::KEY_SWITCH_VALUE, otherwise KeyType::KEY_TYPE_STRING is assumed. KeySwitch::KEY_SWITCH_VALUE Next parameter is a pointer to the value that will be set to the key If no KeySwitch::KEY_SWITCH_TYPE was used before, KeySwitch::KEY_TYPE_STRING is assumed. KeySwitch::KEY_SWITCH_UID, KeySwitch::KEY_SWITCH_GID Next parameter is taken as the UID (uid_t) or GID (gid_t) that will be defined on the key. See keySetUID() and keySetGID(). KeySwitch::KEY_SWITCH_MODE Next parameter is taken as access permissions (mode_t) to the key. See keySetAccess(). KeySwitch::KEY_SWITCH_DOMAIN Next parameter is the user domain. See keySetOwner(). KeySwitch::KEY_SWITCH_COMMENT Next parameter is a comment. See keySetComment(). KeySwitch::KEY_SWITCH_NEEDSYNC Needs no extra parameter. Makes keyNew() retrieve the Key from the backend with kdbGetKey(). In the same keyNew() call you can use this tag in conjunction with any other, which will make keyNew() modify only some attributes of the retrieved key, and return it for you. Order of parameters do matter. If the internal call to kdbGetKey() failed, you'll still have a valid, but flaged, key. Check with keyGetFlag(), and errno. You will have to kdbOpen() before using keyNew() with this tag. KeySwitch::KEY_SWITCH_END Must be the last parameter passed to keyNew(). It is always required, unless the keyName is NULL too. Example: 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, // 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,7, // key type and value size (because it is binary) KEY_SWITCH_DOMAIN,"root", // owner (not uid) is root KEY_SWITCH_VALUE,"some data", // value that will be truncated KEY_SWITCH_COMMENT,"value is truncated", 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, // retrieve from storage KEY_SWITCH_END)); // do nothing more ksAppend(ks,keyNew("user/env/alias/ls", // same key KEY_SWITCH_NEEDSYNC, // 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(); Parameters: keyName  a valid name to the key, or NULL to get a simple initialized, but really empty, object See also: keyDel() Returns: a pointer to a new allocated and initialized Key object, or NULL if an invalid keyName was passed (see keySetName()). Definition at line 340 of file key.c. References _Key::flags, kdbGetKey(), KEY_SWITCH_COMMENT, KEY_SWITCH_DOMAIN, KEY_SWITCH_GID, KEY_SWITCH_MODE, KEY_SWITCH_NEEDSYNC, KEY_SWITCH_TYPE, KEY_SWITCH_UID, KEY_SWITCH_VALUE, KEY_TYPE_BINARY, keyInit(), keySetAccess(), keySetComment(), keySetGID(), keySetName(), keySetOwner(), keySetRaw(), keySetString(), keySetType(), and keySetUID(). Referenced by commandEdit(), commandGet(), commandList(), commandMonitor(), commandMove(), commandSet(), kdbGetChildKeys(), kdbGetRootKeys(), kdbGetValue(), kdbLink(), kdbMonitorKey_default(), kdbRemove(), and kdbSetValue().

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. See also: keyNew() Returns: whatever is returned by keyClose() Definition at line 443 of file key.c. References keyClose(). Referenced by commandEdit(), commandGet(), commandList(), commandMonitor(), commandMove(), commandSet(), kdbGetChildKeys(), kdbGetRootKeys(), kdbGetValue(), kdbLink(), kdbMonitorKey_default(), kdbRemove(), kdbSetValue(), ksClose(), and ksCompare().

int keyDup (  const Key *  source, Key *  dest )

Duplicate memory of keys. Both keys have to be initialized with keyInit(). If you have set any dynamic allocated memory for dest, make sure that you keyClose() it. All private attributes of the source key will be copied, including its context on a KeySet, and nothing will be shared between both keys. Parameters: source  has to be a initializised Key dest  will be the new copy of the Key Returns: 0 on success See also: keyClose(), keyInit() Definition at line 2248 of file key.c. References _Key::comment, _Key::data, _Key::dataSize, _Key::flags, _Key::key, keySetComment(), keySetName(), keySetOwner(), keySetRaw(), and _Key::userDomain. Referenced by kdbMonitorKey_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() Example Key *key=keyNew("system/some/name"); ... // Use the key ... keyClose(key); keyInit(key); ... // Reuse the key ... keyDel(key); See also: keyClose() to free the memory allocated within that function. keyNew() and keyDel() for construction and destruction of Keys Returns: always 0; Definition at line 2973 of file key.c. References _Key::access, _Key::flags, _Key::gid, _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() See also: keyInit() how to allocate internal memory and an example keyNew() and keyDel() for construction and destruction of Keys Returns: always 0; Definition at line 3015 of file key.c. References _Key::comment, _Key::data, _Key::key, and _Key::userDomain. Referenced by keyDel().

---