Key :: Name Manipulation Methods

Methods to do various operations on Key names. More...

Functions
ssize_t	keySetName (Key *key, const char *newName)
	Set a new name to a key.
ssize_t	keyAddBaseName (Key *key, const char *baseName)
	Adds baseName to the current key name.
ssize_t	keySetBaseName (Key *key, const char *baseName)
	Sets baseName as the new basename for key.
ssize_t	keyGetNameSize (const Key *key)
	Bytes needed to store the key name without user domain.
ssize_t	keyGetName (const Key *key, char *returnedName, size_t maxSize)
	Get abreviated key name (without user domain name).
char *	keyStealName (const Key *key)
	Returns a pointer to the real internal key abreviated name (without user domain name).
ssize_t	keyGetFullNameSize (const Key *key)
	Bytes needed to store the key name including user domain.
ssize_t	keyGetFullName (const Key *key, char *returnedName, size_t maxSize)
	Get key full name, including the user domain name.
int	keyNameIsSystem (const char *keyName)
	Check whether a key name is under the system namespace or not.
int	keyNameIsUser (const char *keyName)
	Check whether a key name is under the user namespace or not.
ssize_t	keyNameGetRootNameSize (const char *keyName)
	Gets number of bytes needed to store root name of a key name.
ssize_t	keyGetRootNameSize (const Key *key)
	Gets number of bytes needed to store root name of a key.
ssize_t	keyGetRootName (const Key *key, char *returned, size_t maxSize)
	Copy to returned the root name of key.
ssize_t	keyGetFullRootNameSize (const Key *key)
	Calculates number of bytes needed to store full root name of a key.
ssize_t	keyGetFullRootName (const Key *key, char *returned, size_t maxSize)
	Copy to returned the full root name of the key.
ssize_t	keyGetParentNameSize (const Key *key)
	Get the number of bytes needed to store this key's parent name without the ending NULL.
ssize_t	keyGetParentName (const Key *key, char *returnedParent, size_t maxSize)
	Copy this key's parent name into a pre-allocated buffer.
ssize_t	keyNameGetBaseNameSize (const char *keyName)
	Calculates number of bytes needed to store a basename of a key name.
ssize_t	keyGetBaseNameSize (const Key *key)
	Calculates number of bytes needed to store basename of key.
ssize_t	keyGetBaseName (const Key *key, char *returned, size_t maxSize)
	Calculate the basename of a key name and put it in returned.
char *	keyStealBaseName (const Key *key)
	Returns a pointer to the real internal key name where the basename starts.

---

Detailed Description

Methods to do various operations on Key names.

To use them:

#include <kdb.h>

Rules for Key Names

When using Elektra to store your application's configuration and state, please keep in mind the following rules:

• You are not allowed to create keys right under system or user.
• You are not allowed to create folder keys right under system or user. They are reserved for very essential OS subsystems.
• The keys for your application, called say MyApp, should be created under system/sw/MyApp and/or user/sw/MyApp.
• It is suggested to make your application look for default keys under 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.

---

Function Documentation

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

Set a new name to a key. A valid name is of the forms: 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. You should always follow the guidelines for key tree structure creation at Rules for Key Names. A private copy of the key name will be stored, and the newName parameter can be freed after this call. Returns: size in bytes of this new key name, or 0 if newName is empty, or if newName is invalid, in which case errno is set to KDBErrr::KDB_RET_INVALIDKEY. Parameters: key  the key object newName  the new key name See also: keyNew(), keySetOwner() keyGetName(), keyGetFullName(), keyStealName() Definition at line 505 of file key.c. References _Key::flags, _Key::key, KEY_SWITCH_ISSYSTEM, KEY_SWITCH_NAME, KEY_SWITCH_NEEDSYNC, keyNameGetRootNameSize(), strblen(), and _Key::userDomain. Referenced by kdbGetKeyByParent(), kdbGetKeyByParentKey(), kdbRemove(), keyAddBaseName(), keyDup(), keyNew(), and keySetBaseName().

ssize_t keyAddBaseName (  Key *  key, const char *  baseName )

Adds baseName to the current key name. Assumes that key is a directory. baseName is appended to it. The function adds '/' if needed while concatenating. So if key has name "system/dir1/dir2" and this method is called with baseName "mykey", the resulting key will have name "system/dir1/dir2/mykey". Returns: the size in bytes of the new key name See also: keySetBaseName() Definition at line 646 of file key.c. References _Key::key, keySetName(), and strblen().

ssize_t keySetBaseName (  Key *  key, const char *  baseName )

Sets baseName as the new basename for key. All text after the last '/' in the key keyname is erased and baseName is appended. So if key has name "system/dir1/dir2/mykey" and this method is called with baseName "herkey", the resulting key will have name "system/dir1/dir2/herkey". Returns: the size in bytes of the new key name See also: keyAddBaseName() Definition at line 710 of file key.c. References _Key::key, keySetName(), and strblen().

ssize_t keyGetNameSize (  const Key *  key  )

Bytes 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 741 of file key.c. References _Key::key, and strblen(). Referenced by commandGet(), commandMove(), kdbMonitorKey_default(), and ksLookupRE().

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

Get abreviated key name (without user domain name). Returns: number of bytes written to returnedName 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 See also: keyGetNameSize(), keyGetFullName(), keyGetFullNameSize() Definition at line 764 of file key.c. References _Key::key, and strblen(). Referenced by commandGet().

char* keyStealName (  const Key *  key  )

Returns a pointer to the real internal key abreviated name (without user domain name). This is a much more efficient version of keyGetName() and you should use it if you are responsible enough to not mess up things. Parameters: key  the key object See also: keyGetNameSize(), keyGetFullName(), keyGetFullNameSize() keyStealValue() for an example Definition at line 799 of file key.c. References _Key::key. Referenced by ksLookupByName().

ssize_t keyGetFullNameSize (  const Key *  key  )

Bytes 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 815 of file key.c. References _Key::key, strblen(), and _Key::userDomain. Referenced by commandGet(), kdbGetKeyByParentKey(), and keyGetFullName().

ssize_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 845 of file key.c. References _Key::key, keyGetFullNameSize(), strblen(), and _Key::userDomain. Referenced by commandEdit(), commandGet(), commandImport(), kdbGetKeyByParentKey(), keyToStreamBasename(), and ksToStream().

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 932 of file key.c. Referenced by 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 968 of file key.c. Referenced by keyNameGetNamespace().

ssize_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 1005 of file key.c. Referenced by keyGetFullRootNameSize(), keyGetRootNameSize(), and keySetName().

ssize_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 1040 of file key.c. References _Key::key, and keyNameGetRootNameSize(). Referenced by keyGetFullRootName(), and keyGetRootName().

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

Copy to returned the root name of 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 1067 of file key.c. References _Key::key, and keyGetRootNameSize().

ssize_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 1105 of file key.c. References _Key::key, keyIsUser(), keyNameGetRootNameSize(), strblen(), and _Key::userDomain. Referenced by keyGetFullRootName().

ssize_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 written to returned without ending NULL See also: keyGetFullRootNameSize(), keyGetRootName() Definition at line 1134 of file key.c. References _Key::key, keyGetFullRootNameSize(), keyGetRootNameSize(), keyIsUser(), and _Key::userDomain.

ssize_t keyGetParentNameSize (  const Key *  key  )

Get the number of bytes needed to store this key's parent name without the ending NULL. See also: keyGetParentName() for example Definition at line 1185 of file key.c. References _Key::key, and strblen(). Referenced by keyGetParentName(), and ksLookupRE().

ssize_t keyGetParentName (  const Key *  key, char *  returnedParent, size_t  maxSize )

Copy this key's parent name into a pre-allocated buffer. See also: keyGetParentNameSize() Parameters: returnedParent  pre-allocated buffer to copy parent name to maxSize  number of bytes pre-allocated Example: Key *key=keyNew("system/parent/base",KEY_SWITCH_END); char *parentName; size_t parentSize; parentSize=keyGetParentNameSize(key); parentName=malloc(parentSize+1); keyGetParentName(key,parentName,parentSize+1); Definition at line 1240 of file key.c. References _Key::key, and keyGetParentNameSize(). Referenced by ksLookupRE().

ssize_t keyNameGetBaseNameSize (  const char *  keyName  )

Calculates number of bytes needed to store a basename of a key name. Key names that have only root names (e.g. "system" or "user" or "user:domain" ) does not have basenames, thus the function will return 0 bytes. 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 1274 of file key.c. References strblen(). Referenced by keyGetBaseNameSize().

ssize_t keyGetBaseNameSize (  const Key *  key  )

Calculates number of bytes needed to store basename of key. Key names that have only root names (e.g. "system" or "user" or "user:domain" ) does not have basenames, thus the function will return 0 bytes. 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 1298 of file key.c. References _Key::key, and keyNameGetBaseNameSize(). Referenced by commandGet(), and keyGetBaseName().

ssize_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: keyStealBaseName(), keyGetBaseNameSize() Definition at line 1322 of file key.c. References _Key::key, keyGetBaseNameSize(), and strblen(). Referenced by commandGet().

char* keyStealBaseName (  const Key *  key  )

Returns a pointer to the real internal key name where the basename starts. This is a much more efficient version of keyGetBaseName() and you should use it if you are responsible enough to not mess up things. Parameters: key  the object to obtain the basename from See also: keyGetBaseName(), keyGetBaseNameSize() Definition at line 1362 of file key.c. References _Key::key.

---