Elektra  0.9.7
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>
Include dependency graph for key.c:

Functions

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

Detailed Description

Methods for Key manipulation.

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);
int keyDel(Key *key)
A destructor for Key objects.
Definition: key.c:500
Key * keyNew(const char *name,...)
A practical way to fully create a Key object in one step.
Definition: key.c:141
@ KEY_END
Definition: kdbenum.c:97

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_VALUE
    Definition: kdbenum.c:89
  • 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
    Definition: kdbenum.c:93
  • KEY_META
    Next two parameter is a metaname and a metavalue. See keySetMeta().
    Key *k=keyNew("user:/tmp/ex3",
    KEY_META, "comment", "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_META
    Definition: kdbenum.c:94
  • 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
    Definition: kdbenum.c:92
  • 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_SIZE, 4, // now the size is important
    KEY_VALUE, "some data", // sets the binary value ("some")
    KEY_END); // end of args
    Deprecated:
    The flags below are deprecated and KEY_META should be preferred. They remain some time, however, for compatibility:
  • KEY_COMMENT
    Next parameter is a comment. See keySetComment().
    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_COMMENT, "value is truncated",
    KEY_END); // end of args
    @ KEY_COMMENT
    Definition: kdbenum.c:91
Parameters
namea valid name to the key (see keySetName())
Returns
a pointer to a new allocated and initialized Key object.
Return values
NULLon 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
vathe variadic argument list