key.c File Reference

Methods for Key manipulation. More...

#include "kdb.h"
#include "kdbprivate.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 *	keyDup (const Key *source)
	Return a duplicate of a key. More...
int	keyCopy (Key *dest, const Key *source)
	Copy or Clear a key. More...
int	keyDel (Key *key)
	A destructor for Key objects. More...
int	keyClear (Key *key)
	Key Object Cleaner. More...
ssize_t	keyIncRef (Key *key)
	Increment the viability of a key object. More...
ssize_t	keyDecRef (Key *key)
	Decrement the viability of a key object. More...
ssize_t	keyGetRef (const Key *key)
	Return how many references the key has. More...

Detailed Description

Methods for Key manipulation.

Copyright

BSD License (see doc/LICENSE.md or http://www.libelektra.org)

Function Documentation

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:

Key *k = keyNew(0);
// work with it
keyDel (k);

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 it in many different ways depending on the attribute tags you pass as parameters. Tags are represented as keyswitch_t values, and tell keyNew() which Key attribute comes next.

We can also give an empty key name and a KEY_END tag with the same effect as before:

Key *k =keyNew("", KEY_END); // Has the same effect as above
// work with it
keyDel (k);

But we can also give the key a proper name right from the start:

// Create and initialize a key with a name and nothing else
Key *k=keyNew("user/some/example", KEY_END);
// work with it
keyDel (k);

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

keyNew() processes the given argument list even further. 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_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_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_FLAGS, KEY_BINARY | KEY_CASCADING_NAME, // flags
          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
  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_CASCADING_NAME allow the name to start with / useful for ksLookup() and kdbGet() parent/lookup keys
• KEY_META_NAME allow the name to start with arbitrary namespaces useful to compare with metakeys

Deprecated:

These other flags deprecated and KEY_META should be preferred. They remain some time, however, for compatibility:

• KEY_DIR
  Define that the key is a directory rather than a ordinary key. This means its executable bits in its mode are set. But even without this option the key can have subkeys. See keySetDir().
• KEY_OWNER
  Next parameter is the owner. See keySetOwner().
• KEY_UID, KEY_GID
  Next parameter is taken as the UID (uid_t) or GID (gid_t) that will be defined on the key. See keySetUID() and keySetGID().
• KEY_MODE
  Next parameter is taken as mode permissions (int) to the key. See keySetMode().

  Key *k=keyNew("user/tmp/ex3",
          KEY_VALUE, "some data",    // with a simple value
          KEY_MODE, 0777,            // permissions
          KEY_END);                  // end of args

• 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_OWNER, "root",              // owner (not uid) is root
          KEY_UID, 0,                     // root uid
          KEY_END);                       // end of args

Parameters

name	a valid name to the key, or NULL to get a simple initialized, but really empty, object

See also

keyDel()

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()).

Precondition

caller must use va_start and va_end on va

Parameters

va	the variadic argument list