Elektra  0.9.8
Functions
Value Manipulation Methods

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

Collaboration diagram for Value Manipulation Methods:

Functions

const void * keyValue (const Key *key)
 Return a pointer to the real internal key value. More...
 
const char * keyString (const Key *key)
 Get a pointer to the c-string representing the value. More...
 
ssize_t keyGetValueSize (const Key *key)
 Returns the number of bytes needed to store the key value, including the NULL terminator. More...
 
ssize_t keyGetString (const Key *key, char *returnedString, size_t maxSize)
 Copy the string value of a Key into returnedString. More...
 
ssize_t keySetString (Key *key, const char *newStringValue)
 Set the value for key as newStringValue. More...
 
ssize_t keyGetBinary (const Key *key, void *returnedBinary, size_t maxSize)
 Copy the binary value of a Key into returnedBinary. More...
 
ssize_t keySetBinary (Key *key, const void *newBinary, size_t dataSize)
 Set the value of a Key to the binary value newBinary. More...
 

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

◆ keyGetBinary()

ssize_t keyGetBinary ( const Key *  key,
void *  returnedBinary,
size_t  maxSize 
)

Copy the binary value of a Key into returnedBinary.

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 returnedBinary will not be changed.

For string values see keyGetString() and keyIsString().

When returnedBinary is too small to hold the data (maximum size is given by maxSize), the returnedBinary will not be changed and -1 is returned.

Example:
Key *key = keyNew ("user:/keyname", KEY_BINARY, KEY_END);
char buffer[300];
if (keyGetBinary(key,buffer,sizeof(buffer)) == -1)
{
// handle error
}
Key * keyNew(const char *name,...)
A practical way to fully create a Key object in one step.
Definition: key.c:138
@ KEY_BINARY
Definition: kdbenum.c:90
@ KEY_END
Definition: kdbenum.c:95
ssize_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize)
Copy the binary value of a Key into returnedBinary.
Definition: keyvalue.c:448
Parameters
keythe Key object to get the binary value from
returnedBinarypre-allocated memory to store a copy of the Key's value
maxSizenumber of bytes of pre-allocated memory in returnedBinary
Returns
the number of bytes copied to returnedBinary
Return values
0if the binary is empty
-1on NULL pointers
-1if maxSize is 0, too small for the value or larger than SSIZE_MAX
-1if the Key's value is a string
Since
1.0.0
See also
keyValue() for getting a raw pointer to the Key's value
keyGetValueSize() for getting the size of the Key's value
keySetBinary() for setting the binary value of a Key
keyIsBinary() for checking whether a Key's value is binary
keyGetString(), keySetString() for working with string values

◆ keyGetString()

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

Copy the string value of a Key into returnedString.

When there is no value inside the string, 1 will be returned and the returnedString will be empty ("") to avoid programming errors where old strings are shown to the user.

Example:
Key *key = keyNew ("user:/keyname", KEY_END);
char buffer[300];
if (keyGetString(key,buffer,sizeof(buffer)) == -1)
{
// handle error
} else {
printf ("buffer: %s\n", buffer);
}
ssize_t keyGetString(const Key *key, char *returnedString, size_t maxSize)
Copy the string value of a Key into returnedString.
Definition: keyvalue.c:326
Parameters
keythe Key object to get the string from
returnedStringpre-allocated memory to store a copy of the Key's value
maxSizenumber of bytes of allocated memory in returnedString
Returns
the number of bytes actually copied to returnedString, including final NULL
Return values
1if the string is empty
-1on any NULL pointers
-1if the Key's value is binary
-1maxSize is 0, too small for the string or larger than SSIZE_MAX
Since
1.0.0
See also
keyGetValueSize() for getting the size of the Key's value
keyValue() for getting a raw pointer to the Key's value
keyString() for getting a raw char pointer to the Key's value
keyGetBinary(), keyIsBinary() for working with binary data

◆ keyGetValueSize()

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 the value is 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 0 will be returned.

A binary key has no '\0' termination. String types are null-terminated, and the terminator will be considered for the length.

This method can be used with elektraMalloc() before keyGetString() or keyGetBinary() is called.

char *buffer;
buffer = elektraMalloc (keyGetValueSize (key));
// use this buffer to store the value (binary or string)
// pass keyGetValueSize (key) for maxSize
ssize_t keyGetValueSize(const Key *key)
Returns the number of bytes needed to store the key value, including the NULL terminator.
Definition: keyvalue.c:271
void * elektraMalloc(size_t size)
Allocate memory for Elektra.
Definition: internal.c:274
Postcondition
returns the exact amount of bytes needed to store key's value (including NULL terminators)
Parameters
keythe Key object to get the size of the value from
Returns
the number of bytes needed to store the Key's value
Return values
1when there is no data and type is a string
0when there is no data and type is binary
-1on null pointer
Since
1.0.0
See also
keyGetString() for getting the Key's value as a string
keyGetBinary() for getting the Key's value as a binary
keyValue() for getting a pointer to the Key's value

◆ keySetBinary()

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

Set the value of a Key to the binary value newBinary.

A private copy of newBinary will be allocated and saved inside key, so the parameter can be deallocated after the call.

Binary values might be encoded in another way than string values depending on the plugin. Typically character encodings should not take place on binary data. Consider using a string Key instead, if encoding should occur.

When newBinary is a NULL pointer the value will be freed and 0 will be returned.

Read-only keys will stay unchanged after calling this function.

Note
The metadata "binary" will be set to mark that the key is binary from now on. When the Key is already binary the metadata won't be changed. This will only happen in the successful case, but not when -1 is returned.
Precondition
dataSize matches the length of newBinary
newBinary is not NULL and dataSize > 0
key is not read-only
Postcondition
key's value set exactly to the data in newBinary
"binary" key set in key's metadata
Parameters
keythe Key object where the value should be set
newBinarya pointer to any binary data or NULL (to clear the stored value)
dataSizenumber of bytes to copy from newBinary
Returns
the number of bytes actually copied to internal struct storage
Return values
0when the internal binary was freed and is now a null pointer
-1if key is NULL
-1when dataSize is 0 (and newBinary not NULL) or larger than SSIZE_MAX
-1if key is read-only
Since
1.0.0
See also
keyGetBinary() for getting a Key's value as binary
keyIsBinary() to check if the Key's value is binary
keyGetString() and keySetString() for working with string values

◆ keySetString()

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 in UTF-8 universal encoding, regardless of the program's current encoding (if the iconv plugin is available).

Precondition
newStringValue is a NULL terminated string
Postcondition
Value of the Key is set to the UTF-8 encoded value of newStringValue
Metakey meta:/binary is cleared
Parameters
keythe Key for which to set the string value
newStringValueNULL-terminated string to be set as key's value
Returns
the number of bytes actually saved in private struct including final NULL
Return values
1if newStringValue is a NULL pointer, this will make the string empty (string only containing null termination)
-1if key is a NULL pointer
Since
1.0.0
See also
keyString() for getting a pointer to the Key's value
keyGetString() for getting a copy of the Key's value
keySetBinary() for setting binary data

◆ keyString()

const char* keyString ( const Key *  key)

Get a pointer to the c-string representing the value.

Will return "(null)" on null pointers. Will return "(binary)" on binary data not ended with a null byte.

Note
You must not change or delete the returned value. Use the respective functions for that (keySetString(), keyGetString())

It is not checked if it is actually a string, only if it terminates for security reasons.

Postcondition
returned pointer points to the real internal value
value is NULL terminated
Parameters
keythe Key object to get the string value from
Returns
pointer to the c-string representing the Key's value
Return values
""if no data found
(null)on null Key
(binary)on binary Key
Since
1.0.0
See also
keyGetString() for getting a copy of the Key's value as string
keyGetBinary() for getting a copy of the Key's value as binary
keyValue() for getting a pointer to the Key's value as binary

◆ 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(). 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);
int keyDel(Key *key)
A destructor for Key objects.
Definition: key.c:482
ssize_t keySetString(Key *key, const char *newStringValue)
Set the value for key as newStringValue.
Definition: keyvalue.c:386
const void * keyValue(const Key *key)
Return a pointer to the real internal key value.
Definition: keyvalue.c:168

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

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 '\0') here
int i=23;
keySetBinary(key, (void*)&i, 4);
(int*)keyValue(key); // you would expect a pointer to (int)23 here
keyDel(key);
ssize_t keySetBinary(Key *key, const void *newBinary, size_t dataSize)
Set the value of a Key to the binary value newBinary.
Definition: keyvalue.c:519
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() and keyComment(). For string value the behaviour is the same.
Example:
KDB *handle = kdbOpen();
KeySet *ks=ksNew(0, KS_END);
Key *current=0;
kdbGetByName(handle,ks,"system:/sw/my",KDB_O_SORT|KDB_O_RECURSIVE);
while (current=ksNext(ks)) {
size_t size=0;
if (keyIsBinary(current)) {
size=keyGetValueSize(current);
printf("Key %s has a value of size %d bytes. Value: <BINARY>\nComment: %s",
keyName(current),
size,
keyComment(current));
} else {
size=elektraStrLen((char *)keyValue(current));
printf("Key %s has a value of size %d bytes. Value: %s\nComment: %s",
keyName(current),
size,
(char *)keyValue(current),
keyComment(current));
}
}
ksDel (ks);
kdbClose (handle);
KDB * kdbOpen(const KeySet *contract, Key *errorKey)
Opens the session with the Key database.
Definition: kdb.c:417
int kdbClose(KDB *handle, Key *errorKey)
Closes the session with the Key database.
Definition: kdb.c:590
const char * keyName(const Key *key)
Returns a pointer to the abbreviated real internal key name.
Definition: elektra/keyname.c:254
int ksDel(KeySet *ks)
A destructor for KeySet objects.
Definition: keyset.c:455
Key * ksNext(KeySet *ks)
Returns the next Key in a KeySet.
Definition: keyset.c:1609
KeySet * ksNew(size_t alloc,...)
Allocate, initialize and return a new KeySet object.
Definition: keyset.c:229
#define KS_END
End of a list of keys.
Definition: kdbenum.c:156
int ksRewind(KeySet *ks)
Rewinds the KeySet internal cursor.
Definition: keyset.c:1571
int keyIsBinary(const Key *key)
Check if the value of a key is of binary type.
Definition: keytest.c:373
const char * keyComment(const Key *key)
Return a pointer to the real internal key comment.
Definition: meta.c:91
size_t elektraStrLen(const char *s)
Calculates the length in bytes of a string.
Definition: internal.c:385
Precondition
key is not NULL and has stored data
Postcondition
returned pointer points to the stored internal value
if the value is a string, the value is NULL terminated
Parameters
keythe Key from which to get the value
Returns
a pointer to the Key's internal value
Return values
""when there is no value and Key is not binary
0where there is no value and Key is binary
0on NULL pointer
Since
1.0.0
See also
keyGetValueSize() to get the size of the Key's value
keyGetString() for getting the Key's value as string
keyGetBinary() for getting the Key's value as binary