.TH "keyvalue" 3elektra "Sun May 29 2016" "Version 0.8.14" "Elektra" \" -*- nroff -*-
.ad l
.nh
.SH NAME
keyvalue \- Value Manipulation Methods
.PP
Methods to do various operations on Key values\&.  

.SS "Functions"

.in +1c
.ti -1c
.RI "const void * \fBkeyValue\fP (const Key *key)"
.br
.RI "\fIReturn a pointer to the real internal \fCkey\fP value\&. \fP"
.ti -1c
.RI "const char * \fBkeyString\fP (const Key *key)"
.br
.RI "\fIGet the c-string representing the value\&. \fP"
.ti -1c
.RI "ssize_t \fBkeyGetValueSize\fP (const Key *key)"
.br
.RI "\fIReturns the number of bytes needed to store the key value, including the NULL terminator\&. \fP"
.ti -1c
.RI "ssize_t \fBkeyGetString\fP (const Key *key, char *returnedString, size_t maxSize)"
.br
.RI "\fIGet the value of a key as a string\&. \fP"
.ti -1c
.RI "ssize_t \fBkeySetString\fP (Key *key, const char *newStringValue)"
.br
.RI "\fISet the value for \fCkey\fP as \fCnewStringValue\fP\&. \fP"
.ti -1c
.RI "ssize_t \fBkeyGetBinary\fP (const Key *key, void *returnedBinary, size_t maxSize)"
.br
.RI "\fIGet the value of a key as a binary\&. \fP"
.ti -1c
.RI "ssize_t \fBkeySetBinary\fP (Key *key, const void *newBinary, size_t dataSize)"
.br
.RI "\fISet the value of a key as a binary\&. \fP"
.in -1c
.SH "Detailed Description"
.PP 
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 \fBkeyGetString()\fP for that\&. You can save any Unicode Symbols and Elektra will take care that you get the same back, independent of your current environment\&.
.PP
In some situations this idea fails\&. When you need exactly the same value back without any interpretation of the characters, there is \fBkeySetBinary()\fP\&. 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 \fBkeyGetString()\fP\&. To do so, you might use strtod() strtol() and then atol() or atof() to convert back\&.
.PP
To use them: 
.PP
.nf
#include <kdb\&.h>

.fi
.PP
 
.SH "Function Documentation"
.PP 
.SS "ssize_t keyGetBinary (const Key * key, void * returnedBinary, size_t maxSize)"

.PP
Get the value of a key as a binary\&. If the type is not binary -1 will be returned\&.
.PP
When the binary data is empty (this is not the same as ''!) 0 will be returned and the returnedBinary will not be changed\&.
.PP
For string values see \fBkeyGetString()\fP and \fBkeyIsString()\fP\&.
.PP
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\&.
.PP
\fBExample:\fP
.RS 4

.PP
.nf
1 Key *key = keyNew ("user/keyname", KEY_TYPE, KEY_TYPE_BINARY, KEY_END);
2 char buffer[300];
3 
4 if (keyGetBinary(key,buffer,sizeof(buffer)) == -1)
5 {
6         // handle error
7 }

.fi
.PP
.RE
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the object to gather the value from 
.br
\fIreturnedBinary\fP pre-allocated memory to store a copy of the key value 
.br
\fImaxSize\fP number of bytes of pre-allocated memory in \fCreturnedBinary\fP 
.RE
.PP
\fBReturns:\fP
.RS 4
the number of bytes actually copied to \fCreturnedBinary\fP 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI0\fP if the binary is empty 
.br
\fI-1\fP on NULL pointers 
.br
\fI-1\fP if maxSize is 0 
.br
\fI-1\fP if maxSize is too small for string 
.br
\fI-1\fP if maxSize is larger than SSIZE_MAX 
.br
\fI-1\fP on type mismatch: binary expected, but found string 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkeyValue()\fP, \fBkeyGetValueSize()\fP, \fBkeySetBinary()\fP 
.PP
\fBkeyGetString()\fP and \fBkeySetString()\fP as preferred alternative to binary 
.PP
\fBkeyIsBinary()\fP to see how to check for binary type 
.RE
.PP

.SS "ssize_t keyGetString (const Key * key, char * returnedString, size_t maxSize)"

.PP
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\&.
.PP
For binary values see \fBkeyGetBinary()\fP and \fBkeyIsBinary()\fP\&.
.PP
\fBExample:\fP
.RS 4

.PP
.nf
1 Key *key = keyNew ("user/keyname", KEY_END);
2 char buffer[300];
3 
4 if (keyGetString(key,buffer,sizeof(buffer)) == -1)
5 {
6         // handle error
7 } else {
8         printf ("buffer: %s\n", buffer);
9 }

.fi
.PP
.RE
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the object to gather the value from 
.br
\fIreturnedString\fP pre-allocated memory to store a copy of the key value 
.br
\fImaxSize\fP number of bytes of allocated memory in \fCreturnedString\fP 
.RE
.PP
\fBReturns:\fP
.RS 4
the number of bytes actually copied to \fCreturnedString\fP, including final NULL 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI1\fP if the string is empty 
.br
\fI-1\fP on any NULL pointers 
.br
\fI-1\fP on type mismatch: string expected, but found binary 
.br
\fI-1\fP maxSize is 0 
.br
\fI-1\fP if maxSize is too small for string 
.br
\fI-1\fP if maxSize is larger than SSIZE_MAX 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkeyValue()\fP, \fBkeyGetValueSize()\fP, \fBkeySetString()\fP, \fBkeyString()\fP 
.PP
\fBkeyGetBinary()\fP for working with binary data 
.RE
.PP

.SS "ssize_t keyGetValueSize (const Key * key)"

.PP
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\&.
.PP
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\&.
.PP
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\&.
.PP
This method can be used with malloc() before \fBkeyGetString()\fP or \fBkeyGetBinary()\fP is called\&.
.PP
.PP
.nf
1 char *buffer;
2 buffer = malloc (keyGetValueSize (key));
3 // use this buffer to store the value (binary or string)
4 // pass keyGetValueSize (key) for maxSize
.fi
.PP
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the key object to work with 
.RE
.PP
\fBReturns:\fP
.RS 4
the number of bytes needed to store the key value 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI1\fP when there is no data and type is not binary 
.br
\fI0\fP when there is no data and type is binary 
.br
\fI-1\fP on null pointer 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkeyGetString()\fP, \fBkeyGetBinary()\fP, \fBkeyValue()\fP 
.RE
.PP

.SS "ssize_t keySetBinary (Key * key, const void * newBinary, size_t dataSize)"

.PP
Set the value of a key as a binary\&. A private copy of \fCnewBinary\fP will allocated and saved inside \fCkey\fP, so the parameter can be deallocated after the call\&.
.PP
Binary values might be encoded in another way then string values depending on the plugin\&. Typically character encodings should not take place on binary data\&. Consider using a string key instead\&.
.PP
When newBinary is a NULL pointer the binary will be freed and 0 will be returned\&.
.PP
\fBNote:\fP
.RS 4
The meta data 'binary' will be set to mark that the key is binary from now on\&. When the key is already binary the meta data won't be changed\&. This will only happen in the successful case, but not when -1 is returned\&.
.RE
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the object on which to set the value 
.br
\fInewBinary\fP is a pointer to any binary data or NULL to free the previous set data 
.br
\fIdataSize\fP number of bytes to copy from \fCnewBinary\fP 
.RE
.PP
\fBReturns:\fP
.RS 4
the number of bytes actually copied to internal struct storage 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI0\fP when the internal binary was freed and is now a null pointer 
.br
\fI-1\fP if key is a NULL pointer 
.br
\fI-1\fP when dataSize is 0 (but newBinary not NULL) or larger than SSIZE_MAX 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkeyGetBinary()\fP 
.PP
\fBkeyIsBinary()\fP to check if the type is binary 
.PP
\fBkeyGetString()\fP and \fBkeySetString()\fP as preferred alternative to binary 
.RE
.PP

.SS "ssize_t keySetString (Key * key, const char * newStringValue)"

.PP
Set the value for \fCkey\fP as \fCnewStringValue\fP\&. The function will allocate and save a private copy of \fCnewStringValue\fP, so the parameter can be freed after the call\&.
.PP
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 iconv plugin is present\&.
.PP
\fBNote:\fP
.RS 4
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\&.
.RE
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the key to set the string value 
.br
\fInewStringValue\fP NULL-terminated text string to be set as \fCkey's\fP value 
.RE
.PP
\fBReturns:\fP
.RS 4
the number of bytes actually saved in private struct including final NULL 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI1\fP if newStringValue is a NULL pointer, this will make the string empty (string only containing null termination) 
.br
\fI-1\fP if key is a NULL pointer 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkeyGetString()\fP, \fBkeyValue()\fP, \fBkeyString()\fP 
.RE
.PP

.SS "const char* keyString (const Key * key)"

.PP
Get the c-string representing the value\&. Will return (null) on null pointers\&. Will return (binary) on binary data not ended with a null byte\&.
.PP
It is not checked if it is actually a string, only if it terminates for security reasons\&.
.PP
\fBReturns:\fP
.RS 4
the c-string of the value 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI(null)\fP on null keys 
.br
\fI''\fP if no data found 
.br
\fI(binary)\fP on binary keys
.RE
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the key object to get the string from 
.RE
.PP

.SS "const void* keyValue (const Key * key)"

.PP
Return a pointer to the real internal \fCkey\fP value\&. This is a much more efficient version of \fBkeyGetString()\fP \fBkeyGetBinary()\fP, 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 \fBkeyGetString()\fP or \fBkeyGetBinary()\fP instead\&.
.SH "String Handling"
.PP
If \fCkey\fP is string (\fBkeyIsString()\fP), you may cast the returned as a \fC'char *'\fP because you'll get a NULL terminated regular string\&.
.PP
\fBkeyValue()\fP returns '' in string mode when there is no value\&. The reason is 
.PP
.nf
1 key=keyNew(0);
2 keySetString(key,"");
3 keyValue(key); // you would expect "" here
4 keyDel(key);

.fi
.PP
.SH "Binary Data Handling"
.PP
If the data is binary, the size of the value must be determined by \fBkeyGetValueSize()\fP, any strlen() operations are not suitable to determine the size\&.
.PP
\fBkeyValue()\fP returns 0 in binary mode when there is no value\&. The reason is 
.PP
.nf
1 key=keyNew(0);
2 keySetBinary(key, 0, 0);
3 keyValue(key); // you would expect 0 here
4 
5 keySetBinary(key,"", 1);
6 keyValue(key); // you would expect "" (a pointer to '\0') here
7 
8 int i=23;
9 keySetBinary(key, (void*)&i, 4);
10 (int*)keyValue(key); // you would expect a pointer to (int)23 here
11 keyDel(key);

.fi
.PP
.PP
\fBNote:\fP
.RS 4
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 \fBkeyValue()\fP method to set a new value\&. Use \fBkeySetString()\fP or \fBkeySetBinary()\fP instead\&.
.RE
.PP
\fBWarning:\fP
.RS 4
Binary keys will return a NULL pointer when there is no data in contrast to \fBkeyName()\fP, \fBkeyBaseName()\fP, \fBkeyOwner()\fP and \fBkeyComment()\fP\&. For string value the behaviour is the same\&.
.RE
.PP
\fBExample:\fP
.RS 4

.PP
.nf
1 KDB *handle = kdbOpen();
2 KeySet *ks=ksNew(0, KS_END);
3 Key *current=0;
4 
5 kdbGetByName(handle,ks,"system/sw/my",KDB_O_SORT|KDB_O_RECURSIVE);
6 
7 ksRewind(ks);
8 while(current=ksNext(ks)) {
9         size_t size=0;
10         
11         if (keyIsBin(current)) {
12                 size=keyGetValueSize(current);
13                 printf("Key %s has a value of size %d bytes\&. Value: <BINARY>\nComment: %s",
14                         keyName(current),
15                         size,
16                         keyComment(current));
17         } else {
18                 size=elektraStrLen((char *)keyValue(current));
19                 printf("Key %s has a value of size %d bytes\&. Value: %s\nComment: %s",
20                         keyName(current),
21                         size,
22                         (char *)keyValue(current),
23                         keyComment(current));
24         }
25 }
26 
27 ksDel (ks);
28 kdbClose (handle);

.fi
.PP
.RE
.PP
\fBParameters:\fP
.RS 4
\fIkey\fP the key object to work with 
.RE
.PP
\fBReturns:\fP
.RS 4
a pointer to internal value 
.RE
.PP
\fBReturn values:\fP
.RS 4
\fI''\fP when there is no data and key is not binary 
.br
\fI0\fP where there is no data and key is binary 
.br
\fI0\fP on NULL pointer 
.RE
.PP
\fBSee also:\fP
.RS 4
\fBkeyGetValueSize()\fP, \fBkeyGetString()\fP, \fBkeyGetBinary()\fP 
.RE
.PP

.SH "Author"
.PP 
Generated automatically by Doxygen for Elektra from the source code\&.