Provided by: elektra-doc_0.7.1-1_all 
NAME
Key :: Value Manipulation Methods -
Methods to do various operations on Key values.
Functions
const void * keyValue (const Key *key)
ssize_t keyGetValueSize (const Key *key)
ssize_t keyGetString (const Key *key, char *returnedString, size_t maxSize)
ssize_t keySetString (Key *key, const char *newStringValue)
ssize_t keyGetBinary (const Key *key, void *returnedBinary, size_t maxSize)
ssize_t keySetBinary (Key *key, const void *newBinary, size_t dataSize)
const char * keyComment (const Key *key)
ssize_t keyGetCommentSize (const Key *key)
ssize_t keyGetComment (const Key *key, char *returnedComment, size_t maxSize)
ssize_t keySetComment (Key *key, const char *newComment)
Detailed Description
Methods to do various operations on Key values.
A key can contain a value in different format. The most likely situation is, that the value is
interpreted as text. Use keyGetString() for that. You can save any Unicode Symbols and Elektra will take
care that you get the same back, independent of your current environment.
In some situations this idea fails. When you need exactly the same value back without any interpretation
of the characters, there is keySetBinary(). If you use that, its very likely that your Configuration is
not according to the standard. Also for Numbers, Booleans and Date you should use keyGetString(). To do
so, you might use strtod() strtol() and then atol() or atof() to convert back.
To use them:
#include <kdb.h>
Function Documentation
const char* keyComment (const Key *key) Return a pointer to the real internal key comment.
This is a much more efficient version of keyGetComment() and you should use it if you are responsible
enough to not mess up things. You are not allowed to change anything in the memory region the returned
pointer points to.
keyComment() returns '' when there is no keyComment. The reason is
key=keyNew(0);
keySetComment(key,'');
keyComment(key); // you would expect '' here
keyDel(key);
See keySetComment() for more information on comments.
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 keyComment() method to set a new
value. Use keySetComment() instead.
Parameters:
key the key object to work with
Returns:
a pointer to the internal managed comment
0 on NULL pointer
See also:
keyGetCommentSize() for size and keyGetComment() as alternative
ssize_t keyGetBinary (const Key *key, void *returnedBinary, size_tmaxSize) Get the value of a key as a
binary.
If the type is not binary -1 will be returned.
When the binary data is empty (this is not the same as ''!) 0 will be returned and the returnedBinary
will not be changed.
For string values see keyGetString() and keyIsString().
When the returnedBinary is to small to hold the data (its maximum size is given by maxSize), the
returnedBinary will not be changed and -1 is returned.
Example:
Key *key = keyNew ('user/keyname', KEY_TYPE, KEY_TYPE_BINARY, KEY_END);
char buffer[300];
if (keyGetBinary(key,buffer,sizeof(buffer)) == -1)
{
// handle error
}
Parameters:
key the object to gather the value from
returnedBinary pre-allocated memory to store a copy of the key value
maxSize number of bytes of pre-allocated memory in returnedBinary
Returns:
the number of bytes actually copied to returnedBinary
0 if the binary is empty
-1 on NULL pointers
-1 when maxSize is 0, too small to hold the value or larger than SSIZE_MAX
-1 on typing error when the key is not binary
See also:
keyValue(), keyGetValueSize(), keySetBinary()
keyGetString() and keySetString() as preferred alternative to binary
keyIsBinary() to see how to check for binary type
ssize_t keyGetComment (const Key *key, char *returnedComment, size_tmaxSize) Get the key comment.
Comments
A Key comment is description for humans what this key is for. It may be a textual explanation of valid
values, when and why a user or administrator changed the key or any other text that helps the user or
administrator related to that key.
Don't depend on a comment in your program. A user is always allowed to remove or change it in any way he
wants to. But you are allowed or even encouraged to always show the content of the comment to the user
and allow him to change it.
Parameters:
key the key object to work with
returnedComment pre-allocated memory to copy the comments to
maxSize number of bytes that will fit returnedComment
Returns:
the number of bytes actually copied to returnedString, including final NULL
1 if the string is empty
-1 on NULL pointer
-1 if maxSize is 0, not enough to store the comment or when larger then SSIZE_MAX
See also:
keyGetCommentSize(), keySetComment()
ssize_t keyGetCommentSize (const Key *key) Calculates number of bytes needed to store a key comment,
including final NULL.
Use this method to know to size for allocated memory to retrieve a key comment.
See keySetComment() for more information on comments.
For an empty key name you need one byte to store the ending NULL. For that reason 1 is returned.
char *buffer;
buffer = malloc (keyGetCommentSize (key));
// use this buffer to store the comment
// pass keyGetCommentSize (key) for maxSize
Parameters:
key the key object to work with
Returns:
number of bytes needed
1 if there is no comment
-1 on NULL pointer
See also:
keyGetComment(), keySetComment()
ssize_t keyGetString (const Key *key, char *returnedString, size_tmaxSize) Get the value of a key as a
string.
When there is no value inside the string, 1 will be returned and the returnedString will be empty '' to
avoid programming errors that old strings are shown to the user.
For binary values see keyGetBinary() and keyIsBinary().
Example:
Key *key = keyNew ('user/keyname', KEY_END);
char buffer[300];
if (keyGetString(key,buffer,sizeof(buffer)) == -1)
{
// handle error
} else {
printf ('buffer: %s0, buffer);
}
Parameters:
key the object to gather the value from
returnedString pre-allocated memory to store a copy of the key value
maxSize number of bytes of allocated memory in returnedString
Returns:
the number of bytes actually copied to returnedString, including final NULL
1 if the string is empty
-1 on NULL pointer
-1 on type mismatch
maxSize is 0, too small for string or is larger than SSIZE_MAX
See also:
keyValue(), keyGetValueSize(), keySetString()
keyGetBinary() for working with binary data
ssize_t keyGetValueSize (const Key *key) Returns the number of bytes needed to store the key value, including
the NULL terminator.
It returns the correct size, independent of the Key Type. If it is a binary there might be '\0' values in
it.
For an empty string you need one byte to store the ending NULL. For that reason 1 is returned. This is
not true for binary data, so there might be returned 0 too.
A binary key has no '\0' termination. String types have it, so to there length will be added 1 to have
enough space to store it.
This method can be used with malloc() before keyGetString() or keyGetBinary() is called.
char *buffer;
buffer = malloc (keyGetValueSize (key));
// use this buffer to store the value (binary or string)
// pass keyGetValueSize (key) for maxSize
Parameters:
key the key object to work with
Returns:
the number of bytes needed to store the key value
1 when there is no data and type is not binary
0 when there is no data and type is binary
-1 on null pointer
See also:
keyGetString(), keyGetBinary(), keyValue()
ssize_t keySetBinary (Key *key, const void *newBinary, size_tdataSize) Set the value of a key as a binary.
A private copy of newBinary will allocated and saved inside key, so the parameter can be deallocated
after the call.
The filesys backend, when used through a kdbSetKey(), will make the value be kdbbEncoded into a human
readable hex-digit text format.
Consider using a string key instead.
When newBinary is a NULL pointer the binary will be freed and 0 will be returned.
Note:
When the type of the key is already a binary type it won't be changed.
Parameters:
key the object on which to set the value
newBinary is a pointer to any binary data or NULL to free the previous set data
dataSize number of bytes to copy from newBinary
Returns:
the number of bytes actually copied to internal struct storage
0 when the internal binary was freed
-1 on NULL pointer
-1 when dataSize is 0 (but newBinary not NULL) or larger than SSIZE_MAX
See also:
keyGetBinary()
keyIsBinary() to check if the type is binary
keyGetString() and keySetString() as preferred alternative to binary
ssize_t keySetComment (Key *key, const char *newComment) Set a comment for a key.
A key comment is like a configuration file comment. See keySetComment() for more information.
Parameters:
key the key object to work with
newComment the comment, that can be freed after this call.
Returns:
the number of bytes actually saved including final NULL
1 when the comment was freed
-1 on NULL pointer or memory problems
See also:
keyGetComment()
ssize_t keySetString (Key *key, const char *newStringValue) Set the value for key as newStringValue.
The function will allocate and save a private copy of newStringValue, so the parameter can be freed after
the call.
String values will be saved in backend storage, when kdbSetKey() will be called, in UTF-8 universal
encoding, regardless of the program's current encoding, when compiled with --enable-iconv.
The type will be set to KEY_TYPE_STRING. When the type of the key is already a string type it won't be
changed.
Parameters:
key the key to set the string value
newStringValue NULL-terminated text string to be set as key's value
Returns:
the number of bytes actually saved in private struct including final NULL
-1 on NULL pointer
See also:
keyGetString(), keyValue()
const void* keyValue (const Key *key) Return a pointer to the real internal key value.
This is a much more efficient version of keyGetString() keyGetBinary(), and you should use it if you are
responsible enough to not mess up things. You are not allowed to modify anything in the returned string.
If you need a copy of the Value, consider to use keyGetString() or keyGetBinary() instead.
String Handling
If key is string (keyIsString()), you may cast the returned as a 'char *' because you'll get a NULL
terminated regular string.
keyValue() returns '' in string mode when there is no value. The reason is
key=keyNew(0);
keySetString(key,'');
keyValue(key); // you would expect '' here
keyDel(key);
Binary Data Handling
If the data is binary, the size of the value must be determined by keyGetValueSize(), any strlen()
operations are not suitable to determine the size.
keyValue() returns 0 in binary mode when there is no value. The reason is
int i=23;
key=keyNew(0);
keySetBinary(key, 0, 0);
keyValue(key); // you would expect 0 here
keySetBinary(key,'', 1);
keyValue(key); // you would expect '' (a pointer to ' ') here
keySetBinary(key, (void*)&i, 4);
(int*)keyValue(key); // you would expect a pointer to (int)23 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 keyValue() method to set a new
value. Use keySetString() or keySetBinary() instead.
Warning:
Binary keys will return a NULL pointer when there is no data in contrast to keyName(), keyBaseName(),
keyOwner() and keyComment(). For string value the behaviour is the same.
Example:
KDB *handle = kdbOpen();
KeySet *ks=ksNew(0);
Key *current=0;
kdbGetByName(handle,ks,'system/sw/my',KDB_O_SORT|KDB_O_RECURSIVE);
ksRewind(ks);
while(current=ksNext(ks)) {
size_t size=0;
if (keyIsBin(current)) {
size=keyGetValueSize(current);
printf('Key %s has a value of size %d bytes. Value: <BINARY>0omment: %s',
keyName(current),
size,
keyComment(current));
} else {
size=kdbiStrLen((char *)keyValue(current));
printf('Key %s has a value of size %d bytes. Value: %s0omment: %s',
keyName(current),
size,
(char *)keyValue(current),
keyComment(current));
}
}
ksDel (ks);
kdbClose (handle);
Parameters:
key the key object to work with
Returns:
a pointer to internal value
0 where there is no data and key is binary
0 on NULL pointer
See also:
keyGetValueSize(), keyGetString(), keyGetBinary()
Author
Generated automatically by Doxygen for Elektra Projekt from the source code.
Elektra Projekt Tue Sep 13 2011 Key :: Value Manipulation Methods(3)