| Elektra 0.11.0

Functions
key.c File Reference

Methods for Key manipulation. More...

`#include "kdblogger.h"`
`#include <stdio.h>`
`#include "kdb.h"`
`#include "kdbprivate.h"`
`#include <kdbassert.h>`

## Functions
Key * | keyNew (const char *name,...)
| A practical way to fully create a Key object in one step.
Key * | keyVNew (const char *name, va_list va)
| A practical way to fully create a Key object in one step.
Key * | keyCopy (Key *dest, const Key *source, elektraCopyFlags flags)
| Copy or clear a key.
int | keyDel (Key *key)
| A destructor for Key objects.
int | keyClear (Key *key)
| Will clear all internal data of a Key.
uint16_t | keyIncRef (Key *key)
| Increment the reference counter of a Key object.
uint16_t | keyDecRef (Key *key)
| Decrement the reference counter of a Key object.
uint16_t | keyGetRef (const Key *key)
| Return the current reference counter value of a Key object.
int | keyLock (Key *key, elektraLockFlags what)
| Permanently lock parts of a Key.
int | keyIsLocked (const Key *key, elektraLockFlags what)
| Checks which parts of a Key are locked.

## Detailed Description

Methods for Key manipulation.

Copyright
  BSD License (see LICENSE.md or https://www.libelektra.org)

## Function Documentation

## ◆ keyVNew()

Key * keyVNew | ( | const char * | name,
|  | va_list | va
| ) |  |

A practical way to fully create a Key object in one step.

To just get a key object, simple do:

// Create and initialize a key with a name and nothing else
Key *k=keyNew("user:/some/example", KEY_END);
// work with it
keyDel (k);
keyDel
int keyDel(Key *key)
A destructor for Key objects.
Definition key.c:459
keyNew
Key * keyNew(const char *name,...)
A practical way to fully create a Key object in one step.
Definition key.c:144

keyNew() allocates memory for a key object and keyDel() cleans everything up.

If you want the key object to contain a name, value, comment and other meta info read on.

Note
  When you already have a key with similar properties its easier to keyDup() the key.

You can call keyNew() in many different ways depending on the attribute tags you pass as parameters. Tags are represented as elektraKeyFlags values, and tell keyNew() which Key attribute comes next. The Key attribute tags are the following:

- ::KEY_VALUE
  Next parameter is a pointer to the value that will be used. If no KEY_BINARY was used before, a string is assumed.
  // Create and initialize a key with a name and nothing else
  Key *k=keyNew("user:/tmp/ex0",
  KEY_VALUE, "some data", // set a string value
  KEY_END); // end of args
- KEY_SIZE
  Define a maximum length of the value. This is only used when setting a binary key.
  // Create and initialize a key with a name and nothing else
  Key *k=keyNew("user:/tmp/ex1",
  KEY_SIZE, 4, // has no effect on strings
  KEY_VALUE, "some data", // set a string value
  KEY_END); // end of args
  KEY_SIZE
  @ KEY_SIZE
  Definition kdbenum.c:91
- ::KEY_META
  Next two parameter is a metaname and a metavalue. See keySetMeta().
  Key *k=keyNew("user:/tmp/ex3",
  KEY_META, "comment/#0", "a comment", // with a comment
  KEY_META, "owner", "root", // and an owner
  KEY_META, "special", "yes", // and any other metadata
  KEY_END); // end of args
- ::KEY_END
  Must be the last parameter passed to keyNew(). It is always required, unless the `keyName` is 0.
- KEY_FLAGS
  Bitwise disjunction of flags, which don't require one or more values. recommended way to set multiple flags. overrides previously defined flags.
  Key *k=keyNew("user:/tmp/ex3",
  KEY_BINARY, // binary key
  KEY_SIZE, 7, // assume binary length 7
  KEY_VALUE, "some data", // value that will be truncated in 7 bytes
  KEY_END); // end of args
  KEY_BINARY
  @ KEY_BINARY
  Definition kdbenum.c:90

- KEY_BINARY
  Allows one to change the key to a binary key. Make sure that you also pass KEY_SIZE before you set the value. Otherwise it will be cut off with first \0 in the string. So this flag toggle from keySetString() to keySetBinary(). If no value (nor size) is given, it will be a NULL key.

  // Create and initialize a key with a name and nothing else
  Key *k=keyNew("user:/tmp/ex2",
  KEY_BINARY,
  KEY_SIZE, 4, // now the size is important
  KEY_VALUE, "some data", // sets the binary value ("some")
  KEY_END); // end of args
  Key *k=keyNew("user:/tmp/ex4",
  KEY_BINARY, // key type
  KEY_SIZE, 7, // assume binary length 7
  KEY_VALUE, "some data", // value that will be truncated in 7 bytes
  KEY_META, "comment/#0", "value is truncated",
  KEY_END); // end of args

Precondition
  `name` is a valid Key name
  Variable arguments are a valid combination

Postcondition
  returns a new, fully initialized Key object with the valid Key name and all data given by variable arguments

Parameters

  name | a valid name to the key (see keySetName())

Returns
  a pointer to a new allocated and initialized Key object.

Return values

  NULL | on allocation error or if an invalid `name` was passed (see keySetName()).

Since
  1.0.0

See also
  keyDel() for deallocating a created Key object
  keySetName() for rules about which names are considered valid

Precondition
  caller must use va_start and va_end on va

Parameters

  va | the variadic argument list