Main Page | Modules | File List

Key Class Methods

The Key Class and its 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
}
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 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)
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)

Detailed Description

The Key Class and its methods.

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:

Described here the methods to get and set, and make various manipulations in the objects of class Key.

Enumeration Type Documentation

enum KeyFlags
 

Flags that can be used with keys.

See also:
keyCompare()

kdbMonitorKey() the diffMask parameter

kdbMonitorKeys() the diffMask parameter

keyGetFlag()

Enumeration values:
KEY_FLAG_HASTYPE  Flag for the key type
KEY_FLAG_HASKEY  Flag for the key name
KEY_FLAG_HASDATA  Flag for the key data
KEY_FLAG_HASDOMAIN  Flag for the key user domain
KEY_FLAG_HASCOMMENT  Flag for the key comment
KEY_FLAG_HASUID  Flag for the key UID
KEY_FLAG_HASGID  Flag for the key GID
KEY_FLAG_HASPRM  Flag for the key permissions
KEY_FLAG_HASTIME  Flag for the key change time
KEY_FLAG_NEEDSYNC  Flags that key needs syncronization
KEY_FLAG_FLAG  General purpose flag that has semantics only to your app

Definition at line 134 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 97 of file kdb.h.

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().

The type number is a value between 0 and 255. If you define it bigger than KEY_TYPE_STRING, it will be still treated as a string (in the terms of Unicode handling). If you define it between KEY_TYPE_BINARY and KEY_TYPE_STRING, Elektra will handle it as a binary, 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 72 of file kdb.h.

Function Documentation

int keyClearFlag (  Key *  key  ) 
 

Clear the general flag in the Key

The flag has no semantics to the library, only to your application.

See also:
keyGetFlag()

keySetFlag()

Returns:
0, unless key is invalid.

Definition at line 2118 of file key.c.

References KDB_RET_UNINITIALIZED, KEY_FLAG_FLAG, and keyIsInitialized().

int keyClose (  Key *  key  ) 
 

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.

See also:
keyInit() for usage example

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().

u_int32_t keyCompare (  const Key *  key1,
const Key *  key2
) 
 

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 KEY_FLAG_* flags.

Returns:
a bit array poiting the differences
See also:
ksCompare() for examples and more detailed description

KeyFlags

Definition at line 1339 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().

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

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.

Parameters:
source the source key
dest the new copy of the key
Returns:
0 on success
See also:
keyClose()

keyInit()

Definition at line 1074 of file key.c.

References keyClose(), keySetComment(), keySetName(), keySetOwner(), and keySetRaw().

Referenced by kdbMonitorKey().

mode_t keyGetAccess (  const Key *  key  ) 
 

Return the key access permissions.

Definition at line 1191 of file key.c.

References KDB_RET_UNINITIALIZED, and keyIsInitialized().

Referenced by kdbSetKey(), and keyToStream().

time_t keyGetATime (  const Key *  key  ) 
 

Get last time the key data was read from disk.

Definition at line 1240 of file key.c.

References KDB_RET_UNINITIALIZED, and keyIsInitialized().

size_t keyGetBaseName (  const Key *  key,
char *  returned,
size_t  maxSize
) 
 

Calculate the basename of a key name and put it in returned.

Some examples:

  • basename of system/some/keyname is keyname
  • basename of "user/tmp/some key" is "some key"

Parameters:
key the key to extract basename from
returned a pre-allocated buffer to store the basename
maxSize size of the returned buffer
Returns:
number of bytes copied to returned, or 0 and errno is set
See also:
keyGetBaseNameSize()

Definition at line 2055 of file key.c.

References KDB_RET_NOKEY, KDB_RET_NULLKEY, KDB_RET_TRUNC, KDB_RET_UNINITIALIZED, keyGetBaseNameSize(), and keyIsInitialized().

Referenced by commandGet().

size_t keyGetBaseNameSize (  const Key *  key  ) 
 

Calculates number of bytes needed to store basename of a key.

Basenames are denoted as:

  • system/some/thing/basename
  • user:domain/some/thing/basename

Returns:
number of bytes needed without ending NULL
See also:
keyNameGetBaseNameSize()

Definition at line 1942 of file key.c.

References keyIsInitialized(), and keyNameGetBaseNameSize().

Referenced by commandGet(), and keyGetBaseName().

size_t keyGetBinary (  const Key *  key,
void *  returnedBinary,
size_t  maxSize
) 
 

Get the value of a binary or string key.

Parameters:
returnedBinary pre-allocated memory to store a copy of the key value
maxSize number of bytes of pre-allocated memory
Returns:
the number of bytes actually copied
See also:
keySetBinary()

keyGetString()

Definition at line 929 of file key.c.

References KDB_RET_NODATA, KDB_RET_TRUNC, KDB_RET_UNINITIALIZED, and keyIsInitialized().

size_t keyGetComment (  const Key *  key,
char *  returnedDesc,
size_t  maxSize
) 
 

Get the key comment.

A Key comment is pretty much as a comment in a text configuration file.

Parameters:
returnedDesc pre-allocated memory to copy the comments to
maxSize number of bytes that will fit returnedDesc
Returns:
number of bytes written
See also:
keyGetCommentSize()

keySetComment()

Definition at line 678 of file key.c.

References KDB_RET_NODESC, KDB_RET_TRUNC, KDB_RET_UNINITIALIZED, and keyIsInitialized().

Referenced by commandGet().

size_t keyGetCommentSize (  const Key *  key  ) 
 

Calculates number of bytes needed to store a key comment, including final NULL.

Use this method to allocate memory to retrieve a key comment.

Returns:
number of bytes needed
See also:
keyGetComment()

keySetComment()

Definition at line 751 of file key.c.

References KDB_RET_NODESC, KDB_RET_UNINITIALIZED, and keyIsInitialized().

Referenced by commandGet().

time_t keyGetCTime (  const Key *  key  ) 
 

Get last time the key was stated from disk.

Definition at line 1254 of file key.c.

References KDB_RET_UNINITIALIZED, and keyIsInitialized().

size_t keyGetDataSize (  const Key *  key  ) 
 

Returns the number of bytes of the key value

This method is used with malloc() before a keyGetValue().

Returns:
the number of bytes needed to store the key value
See also:
keyGetValue()

Definition at line 311 of file key.c.

References KDB_RET_UNINITIALIZED, and keyIsInitialized().

Referenced by commandGet(), and commandMonitor().

int keyGetFlag (  const Key *  key  ) 
 

Get the flag from the Key.

The flag has no semantics to the library, only to your application.

See also:
keySetFlag()

keyClearFlag()

Returns:
1 if flag is set, 0 otherwise

Definition at line 2143 of file key.c.

References KDB_RET_UNINITIALIZED, KEY_FLAG_FLAG, and keyIsInitialized().

size_t keyGetFullName (  const Key *  key,
char *  returnedName,
size_t  maxSize
) 
 

Get key full name, including the user domain name.

Returns:
number of bytes written
Parameters:
key the key object
returnedName pre-allocated memory to write the key name
maxSize maximum number of bytes that will fit in returnedName, including the final NULL

Definition at line 388 of file key.c.

References KDB_RET_TRUNC, and keyGetFullNameSize().

Referenced by commandEdit(), commandGet(), commandList(), kdbGetChildKeys(), kdbGetKeyByParentKey(), and keyToStream().

size_t keyGetFullNameSize (  const Key *  key  ) 
 

Space needed to store the key name including user domain

Returns:
number of bytes needed to store key name including user domain
See also:
keyGetFullName()

keyGetNameSize()

Definition at line 360 of file key.c.

References KDB_RET_UNINITIALIZED, and keyIsInitialized().

Referenced by commandGet(), kdbGetChildKeys(), kdbGetKeyByParentKey(), and keyGetFullName().

size_t keyGetFullRootName (  const Key *  key,
char *  returned,
size_t  maxSize
) 
 

Copy to returned the full root name of the key.

Some examples:

  • root of system/some/key is system
  • root of user:denise/some/key is user:denise
  • root of user/env/env1 is user:$USER

This method is more robust then keyGetRootName()

Parameters:
key the key to extract root from
returned a pre-allocated buffer to store the rootname
maxSize size of the returned buffer
Returns:
number of bytes needed without ending NULL
See also:
keyGetFullRootNameSize()

keyGetRootName()

Definition at line 2015 of file key.c.

References KDB_RET_NOKEY, KDB_RET_TRUNC, KDB_RET_UNINITIALIZED, keyGetFullRootNameSize(), and keyIsInitialized().

size_t keyGetFullRootNameSize (  const Key *  key  ) 
 

Calculates number of bytes needed to store full root name of a key.

Possible root key names are system, user or user:someuser. In contrast to keyGetRootNameSize(), this method considers the user domain part, and you should prefer this one.

Returns:
number of bytes needed without ending NULL
See also:
keyNameGetRootNameSize()

keyGetRootNameSize()

Definition at line 1873 of file key.c.

References keyIsUser(), and keyNameGetRootNameSize().

Referenced by keyGetFullRootName().

gid_t keyGetGID (  const Key *  key  ) 
 

Get the system's group ID of a key

Returns:
the system's GID of the key
See also:
keySetGID()

keyGetUID()

Definition at line 1156 of file key.c.

References KDB_RET_UNINITIALIZED, and keyIsInitialized().

Referenced by kdbSetKey(), and keyToStream().

time_t keyGetMTime (  const Key *  key  ) 
 

Get last modification time of the key on disk.

Definition at line 1225 of file key.c.

References KDB_RET_UNINITIALIZED, and keyIsInitialized().

size_t keyGetName (  const Key *  key,
char *  returnedName,
size_t  maxSize
) 
 

Get abreviated key name (without user domain name)

Returns:
number of bytes written
Parameters:
key the key object
returnedName pre-allocated memory to write the key name
maxSize maximum number of bytes that will fit in returnedName, including the final NULL

Definition at line 427 of file key.c.

References KDB_RET_NOKEY, KDB_RET_TRUNC, KDB_RET_UNINITIALIZED, and keyIsInitialized().

Referenced by commandGet().

size_t keyGetNameSize (  const Key *  key  ) 
 

Space needed to store the key name without user domain

Returns:
number of bytes needed to store key name without user domain
See also:
keyGetName()

keyGetFullNameSize()

Definition at line 340 of file key.c.

References KDB_RET_UNINITIALIZED, and keyIsInitialized().

Referenced by commandGet(), and kdbMonitorKey().

int keyGetNamespace (  const Key *  key  ) 
 

Return the namespace of a key

Currently valid namespaces are KEY_NS_SYSTEM and KEY_NS_USER.

Returns:
KEY_NS_SYSTEM, KEY_NS_USER or 0
See also:
keyNameGetNameSpace()

keyIsUser()

keyIsSystem()

KeyNamespace

Definition at line 1763 of file key.c.

References keyIsInitialized(), and keyNameGetNamespace().

size_t keyGetOwner (  const Key *  key,
char *  returned,
size_t  maxSize
) 
 

Return the user domain of the key.

  • Given user:someuser/..... return someuser
  • Given user:some.user/.... return some.user
  • Given user/.... return the current user

Only user/... keys have user domains. For system/... keys (that doesn't have user domains) nothing is returned.

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.

Parameters:
key the object to work with
returned a pre-allocated space to store the owner
maxSize maximum number of bytes that fit returned
Returns:
number of bytes written to buffer
See also:
keySetName()

keySetOwner()

keyGetFullName()

Definition at line 603 of file key.c.

References KDB_RET_NODOMAIN, KDB_RET_TRUNC, KDB_RET_UNINITIALIZED, and keyIsInitialized().

size_t keyGetParent (  const Key *  key,
char *  returnedParent,
size_t  maxSize
) 
 

Copy this key's parent name into a pre-allocated buffer.

See also:
keyGetParentSize()
Parameters:
returnedParent pre-allocated buffer to copy parent name to
maxSize number of bytes pre-allocated

Definition at line 1314 of file key.c.

References KDB_RET_TRUNC, and keyGetParentSize().

size_t keyGetParentSize (  const Key *  key  ) 
 

Get the number of bytes needed to store this key's parent name.

See also:
keyGetParent()

Definition at line 1270 of file key.c.

References KDB_RET_NOKEY, KDB_RET_UNINITIALIZED, and keyIsInitialized().

Referenced by keyGetParent().

size_t keyGetRootName (  const Key *  key,
char *  returned,
size_t  maxSize
) 
 

Copy to returned the root name of the key.

Some examples:

  • root of system/some/key is system
  • root of user:denise/some/key is user
  • root of user/env/env1 is user

Use keyGetFullRootName() to get also the user domain.

Parameters:
key the key to extract root from
returned a pre-allocated buffer to store the rootname
maxSize size of the returned buffer
Returns:
number of bytes needed without ending NULL
See also:
keyNameGetRootNameSize()

keyGetRootNameSize()

keyGetFullRootName()

Definition at line 1971 of file key.c.

References KDB_RET_NOKEY, KDB_RET_TRUNC, KDB_RET_UNINITIALIZED, keyGetRootNameSize(), and keyIsInitialized().

size_t keyGetRootNameSize (  const Key *  key  ) 
 

Gets number of bytes needed to store root name of a key.

Possible root key names are system or user . This method does not consider the user domain in user:username keys.

Returns:
number of bytes needed without the ending NULL
See also:
keyGetFullRootNameSize()

keyNameGetRootNameSize()

Definition at line 1850 of file key.c.

References keyIsInitialized(), and keyNameGetRootNameSize().

Referenced by keyGetRootName().

size_t keyGetString (  const Key *  key,
char *  returnedString,
size_t  maxSize
) 
 

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.

Parameters:
returnedString pre-allocated memory to store a copy of the key value
maxSize number of bytes of pre-allocated memory
Returns:
the number of bytes actually copied
See also:
keySetString()

Definition at line 867 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().

u_int8_t keyGetType (  const Key *  key  ) 
 

Returns the key data type.

See also:
keySetType()

KeyType

Returns:
the key type

Definition at line 203 of file key.c.

References KDB_RET_UNINITIALIZED, KEY_TYPE_UNDEFINED, and keyIsInitialized().

Referenced by commandGet(), commandSet(), and keyToStream().

uid_t keyGetUID (  const Key *  key  ) 
 

Get the user ID of a key

Although usually the same, the UID of a key is not related to its user domain.

Returns:
the system's UID of the key
See also:
keyGetGID()

keySetUID()

keyGetOwner()

Definition at line 1112 of file key.c.

References KDB_RET_UNINITIALIZED, and keyIsInitialized().

Referenced by kdbSetKey(), and keyToStream().

int keyInit (  Key *  key  ) 
 

Initializes a Key object.

Every Key object that will be used must be initialized first, to setup pointers, counters, etc.

Example 1:
Key *key;

key=malloc(sizeof(Key));
keyInit(key);
// do something with key...
keyClose(key);
free(key);
Example 2:
Key key;

keyInit(&key);
// do something with key...
keyClose(&key);
See also:
keyClose()

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(), kdbSetKey(), keySetAccess(), keySetComment(), keySetGID(), keySetName(), keySetOwner(), keySetRaw(), keySetType(), and keySetUID().

int keyIsDir (  const Key *  key  ) 
 

Check if a key is folder key

Folder keys have no value.

Returns:
1 if key is a folder, 0 otherwise
See also:
keyIsLink()

keyGetType()

Definition at line 1780 of file key.c.

References KEY_TYPE_DIR, and keyIsInitialized().

Referenced by kdbGetKey(), and kdbSetKey().

int keyIsInitialized (  const Key *  key  ) 
 

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.

See also:
keyInit()

keyClose()

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(), keyGetMTime(), keyGetName(), keyGetNameSize(), keyGetNamespace(), keyGetOwner(), keyGetParentSize(), keyGetRootName(), keyGetRootNameSize(), keyGetString(), keyGetType(), keyGetUID(), keyIsDir(), keyIsLink(), keyIsSystem(), keyIsUser(), keySetAccess(), keySetComment(), keySetFlag(), keySetGID(), keySetName(), keySetOwner(), keySetRaw(), keySetType(), keySetUID(), and keyToStream().

int keyIsLink (  const Key *  key  ) 
 

Check if a key is a link key

The value of link keys is the key they point to.

Returns:
1 if key is a link, 0 otherwise
See also:
keyIsDir()

keyGetType()

Definition at line 1797 of file key.c.

References KEY_TYPE_LINK, and keyIsInitialized().

Referenced by kdbGetChildKeys(), kdbSetKey(), and kdbStatKey().

int keyIsSystem (  const Key *  key  ) 
 

Check whether a key is under the system namespace or not

Returns:
1 if key name begins with system, 0 otherwise
See also:
keyNameIsSystem()

keyIsUser()

keyNameIsUser()

Definition at line 1703 of file key.c.

References keyIsInitialized(), and keyNameIsSystem().

int keyIsUser (  const Key *  key  ) 
 

Check whether a key is under the user namespace or not

Returns:
1 if key name begins with "user", 0 otherwise
See also:
keyNameIsSystem()

keyIsSystem()

keyNameIsUser()

Definition at line 1721 of file key.c.

References keyIsInitialized(), and keyNameIsUser().

Referenced by keyGetFullRootNameSize().

size_t keyNameGetBaseNameSize (  const char *  keyName  ) 
 

Calculates number of bytes needed to store basename of a key name.

Basenames are denoted as:

  • system/some/thing/basename
  • user:domain/some/thing/basename

Returns:
number of bytes needed without ending NULL
See also:
keyGetBaseNameSize()

Definition at line 1896 of file key.c.

References keyNameGetRootNameSize().

Referenced by keyGetBaseNameSize().

int keyNameGetNamespace (  const char *  keyName  ) 
 

Return the namespace of a key name

Currently valid namespaces are KEY_NS_SYSTEM and KEY_NS_USER.

Returns:
KEY_NS_SYSTEM, KEY_NS_USER or 0
See also:
keyGetNamespace()

keyIsUser()

keyIsSystem()

KeyNamespace

Definition at line 1743 of file key.c.

References KEY_NS_SYSTEM, KEY_NS_USER, keyNameIsSystem(), and keyNameIsUser().

Referenced by keyGetNamespace().

size_t keyNameGetRootNameSize (  const char *  keyName  ) 
 

Gets number of bytes needed to store root name of a key name

Possible root key names are system, user or user:someuser .

Returns:
number of bytes needed without ending NULL
Parameters:
keyName the name of the key
See also:
keyGetRootNameSize()

Definition at line 1814 of file key.c.

Referenced by keyGetFullRootNameSize(), keyGetRootNameSize(), keyNameGetBaseNameSize(), and keySetName().

int keyNameIsSystem (  const char *  keyName  ) 
 

Check whether a key name is under the system namespace or not

Returns:
1 if string begins with system , 0 otherwise
Parameters:
keyName the name of a key
See also:
keyIsSystem()

keyIsUser()

keyNameIsUser()

Definition at line 1665 of file key.c.

Referenced by keyIsSystem(), and keyNameGetNamespace().

int keyNameIsUser (  const char *  keyName  ) 
 

Check whether a key name is under the user namespace or not

Returns:
1 if string begins with user, 0 otherwise
Parameters:
keyName the name of a key
See also:
keyIsSystem()

keyIsUser()

keyNameIsSystem()

Definition at line 1684 of file key.c.

Referenced by keyIsUser(), and keyNameGetNamespace().

int keyNeedsSync (  const Key *  key  ) 
 

Test if a Key object was changed after retrieved from disk.

Returns:
1 if the key was changed, 0 otherwise.

Definition at line 188 of file key.c.

References KEY_FLAG_NEEDSYNC.

Referenced by kdbSetKeys().

int keySetAccess (  Key *  key,
mode_t  mode
) 
 

Set the key access permissions.

Definition at line 1208 of file key.c.

References KDB_RET_UNINITIALIZED, KEY_FLAG_HASPRM, KEY_FLAG_NEEDSYNC, keyInit(), and keyIsInitialized().

Referenced by commandSet().

size_t keySetBinary (  Key *  key,
const void *  newBinary,
size_t  dataSize
) 
 

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.

Parameters:
newBinary random bytes
dataSize number of bytes to copy from newBinary
Returns:
the number of bytes actually copied
See also:
keyGetBinary()

keyGetString()

keySetString()

Definition at line 966 of file key.c.

References KEY_TYPE_BINARY, keySetRaw(), and keySetType().

Referenced by commandSet().

size_t keySetComment (  Key *  key,
const char *  newComment
) 
 

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.

Parameters:
newComment the comment, that can be freed after this call.
Returns:
the number of bytes copied
See also:
keyGetComment()

Definition at line 711 of file key.c.

References KDB_RET_UNINITIALIZED, KEY_FLAG_HASCOMMENT, KEY_FLAG_NEEDSYNC, keyInit(), and keyIsInitialized().

Referenced by commandSet(), and keyDup().

int keySetFlag (  Key *  key  ) 
 

Set a general flag in the Key

The flag has no semantics to the library, only to your application.

See also:
keyGetFlag()

keyClearFlag()

Returns:
0, unless key is invalid.

Definition at line 2096 of file key.c.

References KDB_RET_UNINITIALIZED, KEY_FLAG_FLAG, and keyIsInitialized().

int keySetGID (  Key *  key,
gid_t  gid
) 
 

Set the system's group ID of a key

Returns:
the system's GID of the key
See also:
keyGetGID()

keySetUID()

Definition at line 1176 of file key.c.

References KDB_RET_UNINITIALIZED, KEY_FLAG_HASGID, KEY_FLAG_NEEDSYNC, keyInit(), and keyIsInitialized().

Referenced by commandSet().

size_t keySetName (  Key *  key,
const char *  newName
) 
 

Set a new name to a key.

A valid name is of the form:

  • system/something
  • user/something
  • user:username/something

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

Parameters:
newName parameter can be freed after this call.
Returns:
number of bytes of this new key name
Parameters:
key the key object
newName the new key name
See also:
keyGetName()

keySetFullName()

Definition at line 474 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(), kdbSetKey(), kdbSetValue(), and keyDup().

size_t keySetOwner (  Key *  key,
const char *  userDomain
) 
 

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.

Parameters:
userDomain the user domain (or user name)
Returns:
the number of bytes copied
See also:
keySetName()

keyGetOwner()

keyGetFullName()

Definition at line 636 of file key.c.

References KDB_RET_UNINITIALIZED, KEY_FLAG_HASDOMAIN, KEY_FLAG_NEEDSYNC, keyInit(), and keyIsInitialized().

Referenced by keyDup().

size_t keySetRaw (  Key *  key,
const void *  newBinary,
size_t  dataSize
) 
 

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.

Parameters:
newBinary array of bytes to set as the value
dataSize number bytes to use from newBinary, including the final NULL
See also:
keySetType()

keySetString()

keySetBinary()

Definition at line 989 of file key.c.

References KDB_RET_UNINITIALIZED, KEY_FLAG_HASDATA, KEY_FLAG_NEEDSYNC, keyInit(), and keyIsInitialized().

Referenced by keyDup(), keySetBinary(), keySetString(), and keySetType().

size_t keySetString (  Key *  key,
const char *  newString
) 
 

Set the value of a key as a string.

On disk, text will be encoded to UTF-8.

Parameters:
newString NULL-terminated text string
Returns:
the number of bytes actually copied including final NULL
See also:
keyGetString()

Definition at line 906 of file key.c.

References KEY_TYPE_STRING, keySetRaw(), and keySetType().

Referenced by commandSet(), and kdbSetValue().

u_int8_t keySetType (  Key *  key,
u_int8_t  newType
) 
 

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 KEY_TYPE_DIR is the only type that has no value, so when using this method to set to this type, the key value will be freed.

Example:
#define KEY_TYPE_COLOR KEY_TYPE_STRING+4

Key color1;
Key color2;

// Set color1 key
keyInit(&color1);
keySetName(&color1,"user/sw/MyApp/colors/someColor")
keySetString(&color1,"#4B52CA");
keySetComment(&color1,"a custom color");
keySetType(&color1,KEY_TYPE_COLOR);

// Set color2 key
keyInit(&color2);
keySetName(&color2,"system/sw/MyApp/colors/green")
keySetString(&color2,"green");
keySetComment(&color2,"the green color");
keySetType(&color2,KEY_TYPE_COLOR);


// Start affairs with Key database
kdbOpen();

// Commit the keys
kdbSetKey(&color1);
kdbSetKey(&color2);

// Reset memory related to our structures to reuse them later
kdbClose(&color1);
kdbClose(&color2);

// Retrieve keys from the database
keySetName(&color1,"user/sw/MyApp/colors/someColor")
keySetName(&color2,"system/sw/MyApp/colors/green")
kdbGetKey(&color1);
kdbGetKey(&color2);

// End of Key database affairs by now
kdbClose();

// Get the key types, which should be our user-defined KEY_TYPE_COLOR
u_int8_t tcolor1=keyGetType(&color1);
u_int8_t tcolor2=keyGetType(&color2);
See also:
keyGetType()

KeyType

Returns:
the new type

Definition at line 276 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().

int keySetUID (  Key *  key,
uid_t  uid
) 
 

Set the user ID of a key.

Although usually the same, the UID of a key is not related to its user domain.

Returns:
0 on success
See also:
keySetGID()

keyGetUID()

keyGetOwner()

Definition at line 1137 of file key.c.

References KDB_RET_UNINITIALIZED, KEY_FLAG_HASUID, KEY_FLAG_NEEDSYNC, keyInit(), and keyIsInitialized().

Referenced by commandSet().

size_t keyToStream (  const Key *  key,
FILE *  stream,
unsigned long  options
) 
 

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:

  • KDB_O_NUMBERS: Do not convert UID and GID into user and group names
  • KDB_O_CONDENSED: Less human readable, more condensed output

Parameters:
stream where to write output: a file or stdout
options ORed of KDB_O_* options
See also:
ksToStream()

KDBOptions

Returns:
number of bytes written to output

Definition at line 1412 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().

Generated on Tue Aug 31 08:40:42 2004 for Elektra Project by doxygen 1.3.6