Functions¶

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

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

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:

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 }

Parameters:

Returns:

Return values:

See also:

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

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:

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: %s0, buffer);
9 }

Parameters:

Returns:

Return values:

See also:

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.

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

Parameters:

Returns:

Return values:

See also:

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

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.

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.

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

Note:

Parameters:

Returns:

Return values:

See also:

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 iconv plugin is present.

Note:

Parameters:

Returns:

Return values:

See also:

const char* keyString (const Key * key)¶

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.

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

Returns:

Return values:

Parameters:

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.