| Elektra 0.11.0

Functions
Value Manipulation Methods
Key

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

## Functions
const void * | keyValue (const Key *key)
| Return a pointer to the real internal `key` value.
const char * | keyString (const Key *key)
| Get a pointer to 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)
| Copy the string value of a Key into `returnedString`.
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)
| Copy the binary value of a Key into `returnedBinary`.
ssize_t | keySetBinary (Key *key, const void *newBinary, size_t dataSize)
| Set the value of a Key to the binary value `newBinary`.

## 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
  }
  keyNew
  Key * keyNew(const char *name,...)
  A practical way to fully create a Key object in one step.
  Definition key.c:144
  KEY_BINARY
  @ KEY_BINARY
  Definition kdbenum.c:90
  keyGetBinary
  ssize_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize)
  Copy the binary value of a Key into returnedBinary.
  Definition keyvalue.c:443

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);
  }
  keyGetString
  ssize_t keyGetString(const Key *key, char *returnedString, size_t maxSize)
  Copy the string value of a Key into returnedString.
  Definition keyvalue.c:321

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
keyGetValueSize
ssize_t keyGetValueSize(const Key *key)
Returns the number of bytes needed to store the key value, including the NULL terminator.
Definition keyvalue.c:266
elektraMalloc
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

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

# 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);
keySetBinary
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:514

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);
  kdbOpen
  KDB * kdbOpen(const KeySet *contract, Key *errorKey)
  Opens the session with the Key database.
  Definition kdb.c:967
  kdbClose
  int kdbClose(KDB *handle, Key *errorKey)
  Closes the session with the Key database.
  Definition kdb.c:1105
  keyName
  const char * keyName(const Key *key)
  Returns a pointer to the abbreviated real internal key name.
  Definition elektra/keyname.c:429
  ksDel
  int ksDel(KeySet *ks)
  A destructor for KeySet objects.
  Definition keyset.c:521
  ksGetSize
  ssize_t ksGetSize(const KeySet *ks)
  Return the number of Keys that ks contains.
  Definition keyset.c:791
  KS_END
  #define KS_END
  End of a list of keys.
  Definition kdbenum.c:156
  ksAtCursor
  Key * ksAtCursor(const KeySet *ks, elektraCursor pos)
  Return Key at given position pos.
  Definition keyset.c:1978
  ksNew
  KeySet * ksNew(size_t alloc,...)
  Allocate, initialize and return a new KeySet object.
  Definition keyset.c:282
  keyIsBinary
  int keyIsBinary(const Key *key)
  Check if the value of a key is of binary type.
  Definition keytest.c:309
  keyComment
  const char * keyComment(const Key *key)
  Return a pointer to the real internal key comment.
  Definition meta.c:91
  elektraStrLen
  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

  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