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
}

Parameters

key	the Key object to get the binary value from
returnedBinary	pre-allocated memory to store a copy of the Key's value
maxSize	number of bytes of pre-allocated memory in returnedBinary

Returns

the number of bytes copied to returnedBinary

Return values

0	if the binary is empty
-1	on NULL pointers
-1	if maxSize is 0, too small for the value or larger than SSIZE_MAX
-1	if 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);
}

Parameters

key	the Key object to get the string from
returnedString	pre-allocated memory to store a copy of the Key's value
maxSize	number of bytes of allocated memory in returnedString

Returns

the number of bytes actually copied to returnedString, including final NULL

Return values

1	if the string is empty
-1	on any NULL pointers
-1	if the Key's value is binary
-1	maxSize 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

Postcondition

returns the exact amount of bytes needed to store key's value (including NULL terminators)

Parameters

key	the Key object to get the size of the value from

Returns

the number of bytes needed to store the Key's value

Return values

1	when there is no data and type is a string
0	when there is no data and type is binary
-1	on 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

key	the Key object where the value should be set
newBinary	a pointer to any binary data or NULL (to clear the stored value)
dataSize	number of bytes to copy from newBinary

Returns

the number of bytes actually copied to internal struct storage

Return values

0	when the internal binary was freed and is now a null pointer
-1	if key is NULL
-1	when dataSize is 0 (and newBinary not NULL) or larger than SSIZE_MAX
-1	if 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

key	the Key for which to set the string value
newStringValue	NULL-terminated string to be set as key's value

Returns

the number of bytes actually saved in private struct including final NULL

Return values

1	if newStringValue is a NULL pointer, this will make the string empty (string only containing null termination)
-1	if 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

key	the 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);

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);

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);
kdbGetByName(handle,ks,"system:/sw/my",KDB_O_SORT|KDB_O_RECURSIVE);
 
 for (elektraCursor it = 0; it < ksGetSize (ks); ++it)
 {
        Key * current = ksAtCursor (ks, it);
        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);

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

key	the 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
0	where there is no value and Key is binary
0	on 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