Provided by: elektra-doc_0.7.1-1_all 
NAME
Key :: Name Manipulation Methods -
Methods to do various operations on Key names.
Functions
const char * keyName (const Key *key)
ssize_t keyGetNameSize (const Key *key)
ssize_t keyGetName (const Key *key, char *returnedName, size_t maxSize)
ssize_t keySetName (Key *key, const char *newName)
ssize_t keyGetFullNameSize (const Key *key)
ssize_t keyGetFullName (const Key *key, char *returnedName, size_t maxSize)
const char * keyBaseName (const Key *key)
ssize_t keyGetBaseNameSize (const Key *key)
ssize_t keyGetBaseName (const Key *key, char *returned, size_t maxSize)
ssize_t keyAddBaseName (Key *key, const char *baseName)
ssize_t keySetBaseName (Key *key, const char *baseName)
const char * keyOwner (const Key *key)
ssize_t keyGetOwnerSize (const Key *key)
ssize_t keyGetOwner (const Key *key, char *returned, size_t maxSize)
ssize_t keySetOwner (Key *key, const char *owner)
Detailed Description
Methods to do various operations on Key names.
To use them:
#include <kdb.h>
These functions make it easier for c programmers to work with key names. Everything here
can also be done with keySetName, described in key.
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.
· \0 must not occur in names.
· / is the separator.
Function Documentation
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'.
When baseName is 0 or '' nothing will happen and the size of the name is returned.
Warning:
You should not change a keys name once it belongs to a keyset. See ksSort() for more
information.
Parameters:
key the key object to work with
baseName the string to append to the name
Returns:
the size in bytes of the new key name including the ending NULL
-1 if the key had no name
-1 on NULL pointers
See also:
keySetBaseName()
keySetName() to set a new name.
const char* keyBaseName (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. The name might change or even point to a wrong
place after a keySetName(). If you need a copy of the basename consider to use
keyGetBaseName().
keyBaseName() returns '' when there is no keyBaseName. The reason is
key=keyNew(0);
keySetName(key,'');
keyName(key); // you would expect '' here
keySetName(key,'user');
keyName(key); // you would expect '' here
keyDel(key);
Note:
Note that the Key structure keeps its own size field that is calculated by library
internal calls, so to avoid inconsistencies, you must never use the pointer returned
by keyBaseName() method to set a new value. Use keySetBaseName() instead.
Parameters:
key the object to obtain the basename from
Returns:
a pointer to the basename
0 on NULL pointer
See also:
keyGetBaseName(), keyGetBaseNameSize()
keyName() to get a pointer to the name
keyOwner() to get a pointer to the owner
ssize_t keyGetBaseName (const Key *key, char *returned, size_tmaxSize) Calculate the basename
of a key name and put it in returned finalizing the string with NULL.
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
1 on empty name
-1 on NULL pointers
-1 when maxSize is 0 or larger than SSIZE_MAX
See also:
keyBaseName(), keyGetBaseNameSize()
keyName(), keyGetName(), keySetName()
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 1 bytes to store ''.
Basenames are denoted as:
· system/some/thing/basename -> basename
· user:domain/some/thing/base\/name > base\/name
Parameters:
key the key object to work with
Returns:
size in bytes of key's basename including ending NULL
See also:
keyBaseName(), keyGetBaseName()
keyName(), keyGetName(), keySetName()
ssize_t keyGetFullName (const Key *key, char *returnedName, size_tmaxSize) Get key full name,
including the user domain name.
Returns:
number of bytes written
1 on empty name
-1 on NULL pointers
-1 if maxSize is 0 or larger than SSIZE_MAX
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
ssize_t keyGetFullNameSize (const Key *key) Bytes needed to store the key name including user
domain and ending NULL.
Parameters:
key the key object to work with
Returns:
number of bytes needed to store key name including user domain
1 on empty name
-1 on NULL pointer
See also:
keyGetFullName(), keyGetNameSize()
ssize_t keyGetName (const Key *key, char *returnedName, size_tmaxSize) Get abbreviated key
name (without owner name).
When there is not enough space to write the name, nothing will be written and -1 will be
returned.
maxSize is limited to SSIZE_MAX. When this value is exceeded -1 will be returned. The
reason for that is that any value higher is just a negative return value passed by
accident. Of course malloc is not as failure tolerant and will try to allocate.
Returns:
number of bytes written to returnedName
1 when only a null was written
-1 when keyname is longer then maxSize or 0 or any NULL pointer
Parameters:
key the key object to work with
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()
ssize_t keyGetNameSize (const Key *key) Bytes needed to store the key name without owner.
For an empty key name you need one byte to store the ending NULL. For that reason 1 is
returned.
Parameters:
key the key object to work with
Returns:
number of bytes needed, including ending NULL, to store key name without owner
1 if there is is no key Name
-1 on NULL pointer
See also:
keyGetName(), keyGetFullNameSize()
ssize_t keyGetOwner (const Key *key, char *returned, size_tmaxSize) Return the owner 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 a owner. For system/... keys (that doesn't have a key owner) an
empty string ('') is returned.
Although usually the same, the owner of a key is not related to its UID. Owner are related
to WHERE the key is stored on disk, while UIDs are related to mode 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
1 if there is no owner
-1 on NULL pointers
-1 when maxSize is 0, larger than SSIZE_MAX or too small for ownername
See also:
keySetName(), keySetOwner(), keyOwner(), keyGetFullName()
ssize_t keyGetOwnerSize (const Key *key) Return the size of the owner of the Key with
concluding 0.
The returned number can be used to allocate a string. 1 will returned on an empty owner to
store the concluding 0 on using keyGetOwner().
char * buffer;
buffer = malloc (keyGetOwnerSize (key));
// use buffer and keyGetOwnerSize (key) for maxSize
Note:
that -1 might be returned on null pointer, so when you directly allocate afterwards
its best to check if you will pass a null pointer before.
Parameters:
key the key object to work with
Returns:
number of bytes
1 if there is no owner
-1 on NULL pointer
See also:
keyGetOwner()
const char* keyName (const Key *key) Returns a pointer to the abbreviated real internal key
name.
This is a much more efficient version of keyGetName() and can use it if you are
responsible enough to not mess up things. You are not allowed to change anything in the
returned array. The content of that string may change after keySetName() and similar
functions. If you need a copy of the name, consider using keyGetName().
The name will be without owner, see keyGetFullName() if you need the name with its owner.
keyName() returns '' when there is no keyName. The reason is
key=keyNew(0);
keySetName(key,'');
keyName(key); // you would expect '' here
keyDel(key);
Note:
Note that the Key structure keeps its own size field that is calculated by library
internal calls, so to avoid inconsistencies, you must never use the pointer returned
by keyName() method to set a new value. Use keySetName() instead.
Parameters:
key the key object to work with
Returns:
a pointer to the keyname which must not be changed.
0 on NULL pointer
See also:
keyGetNameSize() for the string length
keyGetFullName(), keyGetFullNameSize() to get the full name
keyGetName() as alternative to get a copy
keyOwner() to get a pointer to owner
const char* keyOwner (const Key *key) Return a pointer to the real internal key owner.
This is a much more efficient version of keyGetOwner() and you should use it if you are
responsible enough to not mess up things. You are not allowed to modify the returned
string in any way. If you need a copy of the string, consider to use keyGetOwner()
instead.
keyOwner() returns '' when there is no keyOwner. The reason is
key=keyNew(0);
keySetOwner(key,'');
keyOwner(key); // you would expect '' here
keySetOwner(key,'system');
keyOwner(key); // you would expect '' here
Note:
Note that the Key structure keeps its own size field that is calculated by library
internal calls, so to avoid inconsistencies, you must never use the pointer returned
by keyOwner() method to set a new value. Use keySetOwner() instead.
Parameters:
key the key object to work with
Returns:
a pointer to internal owner
0 on NULL pointer
See also:
keyGetOwnerSize() for the size of the string with concluding 0
keyGetOwner(), keySetOwner()
keyName() for name without owner
keyGetFullName() for name with owner
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'.
Warning:
You should not change a keys name once it belongs to a keyset. See ksSort() for more
information.
Parameters:
key the key object to work with
baseName the string used to overwrite the basename of the key
Returns:
the size in bytes of the new key name
-1 on NULL pointers
See also:
keyAddBaseName()
keySetName() to set a new name
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 owner, to let the library know in which user folder
to save the key. A owner 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.
A private copy of the key name will be stored, and the newName parameter can be freed
after this call.
On invalid names, NULL or '' the name will be '' afterwards.
Warning:
You should not change a keys name once it belongs to a keyset. See ksSort() for more
information.
Returns:
size in bytes of this new key name including ending NULL
-1 if newName is empty or invalid or any NULL pointer
Parameters:
key the key object to work with
newName the new key name
See also:
keyNew(), keySetOwner()
keyGetName(), keyGetFullName(), keyName()
keySetBaseName(), keyAddBaseName() to manipulate a name
ssize_t keySetOwner (Key *key, const char *owner) Set the owner of a key.
A owner is a name of a system user related to a UID. The owner decides on which location
on the disc the key goes.
A private copy is stored, so the passed parameter can be freed after the call.
Parameters:
key the key object to work with
owner the owner (or user name)
Returns:
the number of bytes actually saved including final NULL
1 when owner is freed (by setting 0 or '')
-1 on null pointer or memory problems
See also:
keySetName(), keyGetOwner(), keyGetFullName()
Author
Generated automatically by Doxygen for Elektra Projekt from the source code.