.TH "key.c" 3elektra "Fri Aug 4 2023" "Version 0.11.0" "Elektra" \" -*- nroff -*- .ad l .nh .SH NAME key.c \- Methods for Key manipulation\&. .SH SYNOPSIS .br .PP \fC#include 'kdblogger\&.h'\fP .br \fC#include \fP .br \fC#include 'kdb\&.h'\fP .br \fC#include 'kdbprivate\&.h'\fP .br \fC#include \fP .br .SS "Functions" .in +1c .ti -1c .RI "Key * \fBkeyNew\fP (const char *name,\&.\&.\&.)" .br .RI "A practical way to fully create a Key object in one step\&. " .ti -1c .RI "Key * \fBkeyVNew\fP (const char *name, va_list va)" .br .RI "A practical way to fully create a Key object in one step\&. " .ti -1c .RI "Key * \fBkeyCopy\fP (Key *dest, const Key *source, \fBelektraCopyFlags\fP flags)" .br .RI "Copy or clear a key\&. " .ti -1c .RI "int \fBkeyDel\fP (Key *key)" .br .RI "A destructor for Key objects\&. " .ti -1c .RI "int \fBkeyClear\fP (Key *key)" .br .RI "Will clear all internal data of a Key\&. " .ti -1c .RI "uint16_t \fBkeyIncRef\fP (Key *key)" .br .RI "Increment the reference counter of a Key object\&. " .ti -1c .RI "uint16_t \fBkeyDecRef\fP (Key *key)" .br .RI "Decrement the reference counter of a Key object\&. " .ti -1c .RI "uint16_t \fBkeyGetRef\fP (const Key *key)" .br .RI "Return the current reference counter value of a Key object\&. " .ti -1c .RI "int \fBkeyLock\fP (Key *key, \fBelektraLockFlags\fP what)" .br .RI "Permanently lock parts of a Key\&. " .ti -1c .RI "int \fBkeyIsLocked\fP (const Key *key, \fBelektraLockFlags\fP what)" .br .RI "Checks which parts of a Key are locked\&. " .in -1c .SH "Detailed Description" .PP Methods for Key manipulation\&. .PP \fBCopyright\fP .RS 4 BSD License (see LICENSE\&.md or https://www.libelektra.org) .RE .PP .SH "Function Documentation" .PP .SS "Key* keyVNew (const char * name, va_list va)" .PP A practical way to fully create a Key object in one step\&. To just get a key object, simple do: .PP .PP .nf // Create and initialize a key with a name and nothing else Key *k=keyNew("user:/some/example", KEY_END); // work with it keyDel (k); .fi .PP \fBkeyNew()\fP allocates memory for a key object and \fBkeyDel()\fP cleans everything up\&. .PP If you want the key object to contain a name, value, comment and other meta info read on\&. .PP \fBNote\fP .RS 4 When you already have a key with similar properties its easier to keyDup() the key\&. .RE .PP You can call \fBkeyNew()\fP in many different ways depending on the attribute tags you pass as parameters\&. Tags are represented as \fBelektraKeyFlags\fP values, and tell \fBkeyNew()\fP which Key attribute comes next\&. The Key attribute tags are the following: .IP "\(bu" 2 \fBKEY_VALUE\fP .br Next parameter is a pointer to the value that will be used\&. If no \fBKEY_BINARY\fP was used before, a string is assumed\&. .PP .nf // 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 .fi .PP .IP "\(bu" 2 \fBKEY_SIZE\fP .br Define a maximum length of the value\&. This is only used when setting a binary key\&. .PP .nf // 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 .fi .PP .IP "\(bu" 2 \fBKEY_META\fP .br Next two parameter is a metaname and a metavalue\&. See \fBkeySetMeta()\fP\&. .PP .nf 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 .fi .PP .IP "\(bu" 2 \fBKEY_END\fP .br Must be the last parameter passed to \fBkeyNew()\fP\&. It is always required, unless the \fCkeyName\fP is 0\&. .IP "\(bu" 2 \fBKEY_FLAGS\fP .br Bitwise disjunction of flags, which don't require one or more values\&. recommended way to set multiple flags\&. overrides previously defined flags\&. .PP .nf 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 .fi .PP .IP "\(bu" 2 \fBKEY_BINARY\fP .br Allows one to change the key to a binary key\&. Make sure that you also pass \fBKEY_SIZE\fP before you set the value\&. Otherwise it will be cut off with first \\0 in the string\&. So this flag toggle from \fBkeySetString()\fP to \fBkeySetBinary()\fP\&. If no value (nor size) is given, it will be a NULL key\&. .PP .nf // 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 .fi .PP .PP .PP .nf 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 .fi .PP .PP \fBPrecondition\fP .RS 4 \fCname\fP is a valid Key name .PP Variable arguments are a valid combination .RE .PP \fBPostcondition\fP .RS 4 returns a new, fully initialized Key object with the valid Key name and all data given by variable arguments .RE .PP \fBParameters\fP .RS 4 \fIname\fP a valid name to the key (see \fBkeySetName()\fP) .RE .PP \fBReturns\fP .RS 4 a pointer to a new allocated and initialized Key object\&. .RE .PP \fBReturn values\fP .RS 4 \fINULL\fP on allocation error or if an invalid \fCname\fP was passed (see \fBkeySetName()\fP)\&. .RE .PP \fBSince\fP .RS 4 1\&.0\&.0 .RE .PP \fBSee also\fP .RS 4 \fBkeyDel()\fP for deallocating a created Key object .PP \fBkeySetName()\fP for rules about which names are considered valid .RE .PP \fBPrecondition\fP .RS 4 caller must use va_start and va_end on va .RE .PP \fBParameters\fP .RS 4 \fIva\fP the variadic argument list .RE .PP .PP .SH "Author" .PP Generated automatically by Doxygen for Elektra from the source code\&.