Key :: Name Manipulation Methods

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

Functions

char * keyNameGetOneLevel (const char *keyName, size_t *size)
 Returns one level of the key name.
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 and ending NULL.
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 keyNameGetFullRootNameSize (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 keyNameGetRootNameSize (const char *keyName)
 Gets number of bytes needed to store root name of a key name without user domain.
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 user domain, and with the ending NULL.
ssize_t keyGetParentName (const Key *key, char *returnedParent, size_t maxSize)
 Copy this key's parent name (without user domain) into a pre-allocated buffer.
ssize_t keyNameGetBaseNameSize (const char *keyName)
 Calculates number of bytes needed to store a basename of a key name including the ending NULL.
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 finalizing the string with NULL.
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:

Function Documentation

char* keyNameGetOneLevel ( const char *  keyName,
size_t *  size 
)

Returns one level of the key name.

This method is used to skip repeating '/' and to find escaping chars. Given keyName, this method returns a pointer to the next name level found and changes size to the number of bytes on this level name.

This method is used by keySetName() and others to cleanup parameters before being accepted in the Key object.

// Lets define a key name with a lot of repeating '/' and escaped '/'
char *keyName="user////abc/def\/ghi////jkl///";
char *p;
size_t size=0;
int level=0;
char buffer[20];

p=keyName;
while (*(p=keyNameGetOneLevel(p+size,&size)!=0) {
    level++;

    // copy what we found to a buffer, so we can NULL-terminate it
    strncpy(buffer,p,size);
    buffer[size]=0;

    printf("Level %d name: \"%s\"\n",level,buffer);
}

The above example will produce the following output:

Level 1 name: user
Level 2 name: abc
Level 3 name: def\/ghi
Level 4 name: jkl

Parameters:
keyName the string that will be searched
size the number of bytes of level name found in keyName until the next delimiter ('/')
Returns:
a pointer to the first char of the next level name

Definition at line 569 of file key.c.

Referenced by keyAddBaseName(), keyGetBaseName(), keyGetParentNameSize(), keyNameGetBaseNameSize(), keySetBaseName(), keySetName(), and keyStealBaseName().

ssize_t keySetName ( Key key,
const char *  newName 
)

Set a new name to a key.

A valid name is of the forms:

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 including ending NULL, 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 629 of file key.c.

References _Key::flags, KDB_RET_INVALIDKEY, KDB_RET_NOMEM, _Key::key, KEY_SWITCH_DOMAIN, KEY_SWITCH_ISSYSTEM, KEY_SWITCH_ISUSER, KEY_SWITCH_NAME, KEY_SWITCH_NEEDSYNC, keyNameGetFullRootNameSize(), keyNameGetOneLevel(), keyNameIsSystem(), keyNameIsUser(), keySetOwner(), strblen(), and _Key::userDomain.

Referenced by commandGet(), kdbGetKeyByParent(), kdbGetKeyByParentKey(), kdbRemove(), kdbRename_default(), keyAddBaseName(), keyDup(), keyNew(), keySetBaseName(), and keyUnserialize().

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 including the ending NULL
See also:
keySetBaseName()

Definition at line 786 of file key.c.

References KDB_RET_NOMEM, _Key::key, keyNameGetOneLevel(), 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 lets suppose key has name "system/dir1/dir2/key1". If baseName is "key2", the resulting key name will be "system/dir1/dir2/key2". If baseName is empty or NULL, the resulting key name will be "system/dir1/dir2".

Returns:
the size in bytes of the new key name or -1 on error, and errno is set to KDBErr::KDB_RET_NOMEM
See also:
keyAddBaseName()

Definition at line 849 of file key.c.

References KDB_RET_NOMEM, _Key::key, keyNameGetOneLevel(), keySetName(), and strblen().

ssize_t keyGetNameSize ( const Key key  ) 

Bytes needed to store the key name without user domain.

Returns:
number of bytes needed, including ending NULL, to store key name without user domain
See also:
keyGetName(), keyGetFullNameSize()

Definition at line 920 of file key.c.

References _Key::key, and strblen().

Referenced by commandGet(), commandMove(), kdbMonitorKey_default(), ksGetCommonParentName(), 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 938 of file key.c.

References KDB_RET_NOKEY, KDB_RET_TRUNC, _Key::key, and strblen().

Referenced by commandGet(), and listSingleKey().

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 968 of file key.c.

References _Key::key.

Referenced by ksLookupByName(), and listAllKeysForShell().

ssize_t keyGetFullNameSize ( const Key key  ) 

Bytes needed to store the key name including user domain and ending NULL.

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

Definition at line 984 of file key.c.

References _Key::key, keyNameIsUser(), strblen(), and _Key::userDomain.

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

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 1015 of file key.c.

References KDB_RET_NOKEY, KDB_RET_TRUNC, _Key::key, keyGetFullNameSize(), keyIsUser(), strblen(), and _Key::userDomain.

Referenced by commandEdit(), commandGet(), commandImport(), kdbGetKeyByParentKey(), keySerialize(), keyToStreamBasename(), and listSingleKey().

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 1099 of file key.c.

Referenced by keyNameGetNamespace(), keyNameGetRootNameSize(), and keySetName().

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 1129 of file key.c.

Referenced by keyGetFullNameSize(), keyNameGetNamespace(), keyNameGetRootNameSize(), and keySetName().

ssize_t keyNameGetFullRootNameSize ( 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 with ending NULL
Parameters:
keyName the name of the key
See also:
keyGetFullRootNameSize()

Definition at line 1160 of file key.c.

Referenced by 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 with the ending NULL
See also:
keyGetFullRootNameSize(), keyNameGetRootNameSize()

Definition at line 1195 of file key.c.

References _Key::key, and keyIsUser().

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:

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 with ending NULL
See also:
keyNameGetRootNameSize(), keyGetRootNameSize(), keyGetFullRootName()

Definition at line 1221 of file key.c.

References KDB_RET_NOKEY, KDB_RET_TRUNC, _Key::key, and keyGetRootNameSize().

ssize_t keyNameGetRootNameSize ( const char *  keyName  ) 

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

Some examples:

Parameters:
keyName the name of the key
Returns:
number of bytes needed with ending NULL or -1 if keyName is not a valid name and errno is set to KDBErr::KDB_RET_INVALIDKEY
See also:
keyGetRootNameSize()

Definition at line 1262 of file key.c.

References KDB_RET_INVALIDKEY, keyNameIsSystem(), and keyNameIsUser().

Referenced by keyGetFullRootNameSize().

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 with ending NULL
See also:
keyNameGetRootNameSize(), keyGetRootNameSize()

Definition at line 1304 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:

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 including ending NULL
See also:
keyGetFullRootNameSize(), keyGetRootName()

Definition at line 1335 of file key.c.

References KDB_RET_NOKEY, KDB_RET_TRUNC, _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 user domain, and with the ending NULL.

See also:
keyGetParentName() for example

Definition at line 1383 of file key.c.

References KDB_RET_NOKEY, _Key::key, and keyNameGetOneLevel().

Referenced by keyGetParentName(), and ksLookupRE().

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

Copy this key's parent name (without user domain) into a pre-allocated buffer.

See also:
keyGetParentNameSize()
Parameters:
returnedParent pre-allocated buffer to copy parent name to
maxSize number of bytes pre-allocated
Returns:
number of bytes copied including ending NULL
Example:
Key *key=keyNew("system/parent/base",KEY_SWITCH_END);
char *parentName;
size_t parentSize;

parentSize=keyGetParentNameSize(key);
parentName=malloc(parentSize);
keyGetParentName(key,parentName,parentSize);

Definition at line 1439 of file key.c.

References KDB_RET_TRUNC, _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 including the ending NULL.

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:

Returns:
size in bytes of basename including ending NULL
See also:
keyGetBaseNameSize()

Definition at line 1475 of file key.c.

References keyNameGetOneLevel().

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:

Returns:
size in bytes of key's basename including ending NULL
See also:
keyNameGetBaseNameSize()

Definition at line 1506 of file key.c.

References _Key::key, and keyNameGetBaseNameSize().

Referenced by commandGet().

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

Calculate the basename of a key name and put it in returned finalizing the string with NULL.

Some examples:

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 1529 of file key.c.

References KDB_RET_TRUNC, _Key::key, and keyNameGetOneLevel().

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 1562 of file key.c.

References _Key::key, and keyNameGetOneLevel().


Generated on Sun Mar 25 21:33:36 2007 for Elektra Project by  doxygen 1.5.1