<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>Elektra Projekt: Key :: Basic Methods</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.1 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1>Key :: Basic Methods</h1>
<p>Key construction and initialization methods.
<a href="#_details">More...</a></p>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">Key * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a> (const char *keyName,...)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">Key * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__key.html#gae6ec6a60cc4b8c1463fa08623d056ce3">keyDup</a> (const Key *source)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__key.html#ga6a12cbbe656a1ad9f41b8c681d7a2f92">keyCopy</a> (Key *dest, const Key *source)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ssize_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__key.html#ga6970a6f254d67af7e39f8e469bb162f1">keyIncRef</a> (Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ssize_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__key.html#ga2c6433ca22109e4e141946057eccb283">keyDecRef</a> (Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ssize_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__key.html#ga4aabc4272506dd63161db2bbb42de8ae">keyGetRef</a> (const Key *key)</td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<p>Key construction and initialization methods. </p>
<p>To use them: </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <kdb.h></span>
</pre></div><p>A Key is the essential class that encapsulates key <a class="el" href="group__keyname.html">name </a>, <a class="el" href="group__keyvalue.html">value </a> and <a class="el" href="group__keymeta.html">metainfo </a>. Key properties are:</p>
<ul>
<li><a class="el" href="group__keyname.html">Key name </a></li>
<li><a class="el" href="group__keyvalue.html">Key value </a></li>
<li><a class="el" href="group__keymeta.html#gab92003db4b938594df48807c16766bf7">Data type </a></li>
<li><a class="el" href="group__keyvalue.html#gafb89735689929ff717cc9f2d0d0b46a2">Key comment </a></li>
<li><a class="el" href="group__keyname.html#ga6d612841c829a638a8fbbbd4a31cc54a">Key owner </a></li>
<li><a class="el" href="group__keymeta.html">UID, GID and filesystem-like mode permissions </a></li>
<li><a class="el" href="group__keymeta.html">Mode, change and modification times </a></li>
</ul>
<p>Described here the methods to allocate and free the key. </p>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="ga6a12cbbe656a1ad9f41b8c681d7a2f92"></a><!-- doxytag: member="key.c::keyCopy" ref="ga6a12cbbe656a1ad9f41b8c681d7a2f92" args="(Key *dest, const Key *source)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int keyCopy </td>
<td>(</td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>dest</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>source</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Copy or Clear a key.</p>
<p>Most often you may prefer <a class="el" href="group__key.html#gae6ec6a60cc4b8c1463fa08623d056ce3">keyDup()</a> which allocates a new key and returns a duplication of another key.</p>
<p>But when you need to copy into an existing key, e.g. because it was passed by a pointer in a function you can do so:</p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> h (Key *k)
{
<span class="comment">// receive key c</span>
<a class="code" href="group__key.html#ga6a12cbbe656a1ad9f41b8c681d7a2f92">keyCopy</a> (k, c);
<span class="comment">// the caller will see the changed key k</span>
}
</pre></div><p>The reference counter will not change for the destination key. Affiliation to keysets are also not affected.</p>
<p>When you pass a NULL-pointer as source the data of dest will be cleaned completely and you get a fresh dest key.</p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> g (Key *k)
{
<a class="code" href="group__key.html#ga6a12cbbe656a1ad9f41b8c681d7a2f92">keyCopy</a> (k, 0);
<span class="comment">// k is now an empty and fresh key</span>
}
</pre></div><dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>dest</em> </td><td>the key which will be written to </td></tr>
<tr><td valign="top"></td><td valign="top"><em>source</em> </td><td>the key which should be copied or NULL to clean the destination key</td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>-1 on failure when a NULL pointer was passed for dest or a dynamic property could not be written. </dd>
<dd>
0 when dest was cleaned </dd>
<dd>
1 when source was successfully copied </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__key.html#gae6ec6a60cc4b8c1463fa08623d056ce3">keyDup()</a> to get a duplication of a <a class="el" href="group__key.html" title="Key construction and initialization methods.">Key :: Basic Methods</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga2c6433ca22109e4e141946057eccb283"></a><!-- doxytag: member="key.c::keyDecRef" ref="ga2c6433ca22109e4e141946057eccb283" args="(Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t keyDecRef </td>
<td>(</td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Decrement the viability of a key object.</p>
<p>The reference counter can't be decremented once it reached 0. In that situation nothing will happen and 0 will be returned.</p>
<dl class="return"><dt><b>Returns:</b></dt><dd>the value of the new reference counter </dd>
<dd>
-1 on null pointer </dd>
<dd>
0 when the key is ready to be freed </dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__key.html#ga4aabc4272506dd63161db2bbb42de8ae">keyGetRef()</a>, <a class="el" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a>, <a class="el" href="group__key.html#ga6970a6f254d67af7e39f8e469bb162f1">keyIncRef()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga3df95bbc2494e3e6703ece5639be5bb1"></a><!-- doxytag: member="key.c::keyDel" ref="ga3df95bbc2494e3e6703ece5639be5bb1" args="(Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int keyDel </td>
<td>(</td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>A destructor for Key objects.</p>
<p>Every key created by <a class="el" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a> must be deleted with <a class="el" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a>.</p>
<p>It is save to delete keys which are in a keyset, the number of references will be returned then.</p>
<p>It is save to delete a nullpointer, -1 will be returned then.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to delete </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a>, keyInc(), <a class="el" href="group__key.html#ga4aabc4272506dd63161db2bbb42de8ae">keyGetRef()</a> </dd></dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the value of the reference counter if the key is within keyset(s) </dd>
<dd>
0 when the key was freed </dd>
<dd>
-1 on null pointers </dd></dl>
</div>
</div>
<a class="anchor" id="gae6ec6a60cc4b8c1463fa08623d056ce3"></a><!-- doxytag: member="key.c::keyDup" ref="gae6ec6a60cc4b8c1463fa08623d056ce3" args="(const Key *source)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">Key* keyDup </td>
<td>(</td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>source</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Return a duplicate of a key.</p>
<p>Memory will be allocated as needed for dynamic properties.</p>
<p>The new key will not be member of any KeySet and will start with a new reference counter at 0. A subsequent <a class="el" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> will delete the key.</p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> f (<span class="keyword">const</span> Key * source)
{
Key * dup = <a class="code" href="group__key.html#gae6ec6a60cc4b8c1463fa08623d056ce3">keyDup</a> (source);
<span class="comment">// work with duplicate</span>
<a class="code" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (dup);
<span class="comment">// everything related to dup is freed</span>
<span class="comment">// and source is unchanged</span>
}
</pre></div><p>Like for a new key after <a class="el" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a> a subsequent <a class="el" href="group__keyset.html#ga21eb9c3a14a604ee3a8bdc779232e7b7">ksAppend()</a> makes a KeySet to take care of the lifecycle of the key.</p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> g (<span class="keyword">const</span> Key * source, KeySet * ks)
{
Key * dup = <a class="code" href="group__key.html#gae6ec6a60cc4b8c1463fa08623d056ce3">keyDup</a> (source);
<span class="comment">// work with duplicate</span>
<a class="code" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a> (ks, dup);
<span class="comment">// ksDel(ks) will also free the duplicate</span>
<span class="comment">// source remains unchanged.</span>
}
</pre></div><p>Duplication of keys should be preferred to <a class="el" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a>, because data like owner can be filled with a copy of the key instead of asking the environment. It can also be optimized in the checks, because the keyname is known to be valid.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>source</em> </td><td>has to be an initializised source Key </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 failure or on NULL pointer </dd>
<dd>
a fully copy of source on success </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyset.html#ga21eb9c3a14a604ee3a8bdc779232e7b7">ksAppend()</a>, <a class="el" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> </dd>
<dd>
keyClear(), <a class="el" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga4aabc4272506dd63161db2bbb42de8ae"></a><!-- doxytag: member="key.c::keyGetRef" ref="ga4aabc4272506dd63161db2bbb42de8ae" args="(const Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t keyGetRef </td>
<td>(</td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Return how many references the key has.</p>
<p>The references will be incremented when <a class="el" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey()</a> or <a class="el" href="group__keyset.html#ga21eb9c3a14a604ee3a8bdc779232e7b7">ksAppend()</a> uses the key and will be decremented when <a class="el" href="group__keyset.html#gae42530b04defb772059de0600159cf69">ksPop()</a> is used.</p>
<p><a class="el" href="group__key.html#gae6ec6a60cc4b8c1463fa08623d056ce3">keyDup()</a> will reset the references for dupped key.</p>
<p>For your own applications you can use <a class="el" href="group__key.html#ga6970a6f254d67af7e39f8e469bb162f1">keyIncRef()</a> and keyDelRef() for reference counting. Keys with zero references will be deleted when using <a class="el" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a>.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the number of references </dd>
<dd>
-1 on null pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__key.html#ga6970a6f254d67af7e39f8e469bb162f1">keyIncRef()</a> and <a class="el" href="group__key.html#ga2c6433ca22109e4e141946057eccb283">keyDecRef()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga6970a6f254d67af7e39f8e469bb162f1"></a><!-- doxytag: member="key.c::keyIncRef" ref="ga6970a6f254d67af7e39f8e469bb162f1" args="(Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t keyIncRef </td>
<td>(</td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Increment the viability of a key object.</p>
<p>This function is intended for applications using their own reference counter for key objects. With it you can increment the reference and thus avoid destruction of the object in a subsequent <a class="el" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a>.</p>
<div class="fragment"><pre class="fragment">Key *k;
keyInc (k);
function_that_keyDec(k);
<span class="comment">// work with k</span>
<a class="code" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (k); <span class="comment">// now really free it</span>
</pre></div><p>The reference counter can't be incremented once it reached SSIZE_MAX. In that situation nothing will happen and SSIZE_MAX will be returned.</p>
<dl class="return"><dt><b>Returns:</b></dt><dd>the value of the new reference counter </dd>
<dd>
-1 on null pointer </dd>
<dd>
SSIZE_MAX when maximum exceeded </dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__key.html#ga4aabc4272506dd63161db2bbb42de8ae">keyGetRef()</a>, <a class="el" href="group__key.html#ga2c6433ca22109e4e141946057eccb283">keyDecRef()</a>, <a class="el" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gaf6893c038b3ebee90c73a9ea8356bebf"></a><!-- doxytag: member="key.c::keyNew" ref="gaf6893c038b3ebee90c73a9ea8356bebf" args="(const char *keyName,...)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">Key* keyNew </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>keyName</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"> </td>
<td class="paramname"> <em>...</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>A practical way to fully create a Key object in one step.</p>
<p>This function tries to mimic the C++ way for constructors.</p>
<p>To just get a key object, simple do: </p>
<div class="fragment"><pre class="fragment">Key *k = <a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0);
<span class="comment">// work with it</span>
<a class="code" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (k);
</pre></div><p>If you want the key object to contain a name, value, comment and other meta info read on.</p>
<dl class="note"><dt><b>Note:</b></dt><dd>When you already have a key with similar properties its easier and cheaper to <a class="el" href="group__key.html#gae6ec6a60cc4b8c1463fa08623d056ce3">keyDup()</a> the key.</dd></dl>
<p>Due to ABI compatibility, the <code>Key</code> structure is not defined in kdb.h, only declared. So you can only declare <code>pointers</code> to <code>Keys</code> in your program, and allocate and free memory for them with <a class="el" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a> and <a class="el" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> respectively. See <a href="http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html#AEN135">http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html#AEN135</a></p>
<p>You can call it in many different ways depending on the attribute tags you pass as parameters. Tags are represented as the keyswitch_t values, and tell <a class="el" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a> which Key attribute comes next.</p>
<p>The simplest and minimum way to use it is with no tags, only a key name: </p>
<div class="fragment"><pre class="fragment">Key *nullKey,*emptyNamedKey;
<span class="comment">// Create a key that has no name, is completely empty, but is initialized</span>
nullKey=<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0);
<a class="code" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (nullKey);
<span class="comment">// Is the same as above</span>
nullKey=<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">""</span>, KEY_END);
<a class="code" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (nullKey);
<span class="comment">// Create and initialize a key with a name and nothing else</span>
emptyNamedKey=<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"user/some/example"</span>,KEY_END);
<a class="code" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (emptyNamedKey);
</pre></div><p><a class="el" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a> allocates memory for a key object and cleans everything up. After that, it processes the given argument list.</p>
<p>The Key attribute tags are the following:</p>
<ul>
<li>keyswitch_t::KEY_TYPE <br/>
Next parameter is a type of the value. Default assumed is KEY_TYPE_UNDEFINED. Set this attribute so that a subsequent KEY_VALUE can toggle to <a class="el" href="group__keyvalue.html#ga622bde1eb0e0c4994728331326340ef2">keySetString()</a> or <a class="el" href="group__keyvalue.html#gaa50a5358fd328d373a45f395fa1b99e7">keySetBinary()</a> regarding to <a class="el" href="group__keytest.html#gaea7670778abd07fee0fe8ac12a149190">keyIsString()</a> or <a class="el" href="group__keytest.html#ga9526b371087564e43e3dff8ad0dac949">keyIsBinary()</a>. If you don't use KEY_TYPE but a KEY_VALUE follows afterwards, KEY_TYPE_STRING will be used.</li>
<li>keyswitch_t::KEY_SIZE <br/>
Define a maximum length of the value. This is especially useful for setting a binary key. So make sure you use that before you KEY_VALUE for binary keys.</li>
<li>keyswitch_t::KEY_VALUE <br/>
Next parameter is a pointer to the value that will be set to the key If no keyswitch_t::KEY_TYPE was used before, keyswitch_t::KEY_TYPE_STRING is assumed. If KEY_TYPE was previously passed with a KEY_TYPE_BINARY, you should have passed KEY_SIZE before! Otherwise it will be cut of with first \0 in string!</li>
<li>keyswitch_t::KEY_UID, <code>keyswitch_t::KEY_GID</code> <br/>
Next parameter is taken as the UID (uid_t) or GID (gid_t) that will be defined on the key. See <a class="el" href="group__keymeta.html#gab5f284f5ecd261e0a290095f50ba1af7">keySetUID()</a> and <a class="el" href="group__keymeta.html#ga9e3d0fb3f7ba906e067727b9155d22e3">keySetGID()</a>.</li>
<li>keyswitch_t::KEY_MODE <br/>
Next parameter is taken as mode permissions (mode_t) to the key. See <a class="el" href="group__keymeta.html#ga8803037e35b9da1ce492323a88ff6bc3">keySetMode()</a>.</li>
<li>keyswitch_t::KEY_DIR <br/>
Define that the key is a directory rather than a ordinary key. This means its executable bits in its mode are set. This option allows the key to have subkeys. See <a class="el" href="group__keymeta.html#gaae575bd86a628a15ee45baa860522e75">keySetDir()</a>.</li>
<li>keyswitch_t::KEY_OWNER <br/>
Next parameter is the owner. See <a class="el" href="group__keyname.html#gaa899d9f0251cb98a89761ef112910eca">keySetOwner()</a>.</li>
<li>keyswitch_t::KEY_COMMENT <br/>
Next parameter is a comment. See <a class="el" href="group__keyvalue.html#ga8863a877a84fa46e6017fe72e49b89c1">keySetComment()</a>.</li>
<li>keyswitch_t::KEY_REMOVE <br/>
Mark the key to be removed instead of set it. See <a class="el" href="group__keymeta.html#ga6e14e5f1de26e1318100631a149f2984">keyRemove()</a>.</li>
<li>keyswitch_t::KEY_STAT <br/>
Mark the key to be stated instead of get it. See <a class="el" href="group__keymeta.html#gab8189add5e562bdb148675ee595bd95b">keyStat()</a>.</li>
<li>keyswitch_t::KEY_END <br/>
Must be the last parameter passed to <a class="el" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a>. It is always required, unless the <code>keyName</code> is 0.</li>
</ul>
<dl class="user"><dt><b>Example:</b></dt><dd><div class="fragment"><pre class="fragment">KeySet *ks=<a class="code" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew</a>(0);
<a class="code" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks,<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0)); <span class="comment">// an empty key</span>
<a class="code" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks,<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"user/sw"</span>, <span class="comment">// the name of the key</span>
KEY_END)); <span class="comment">// no more args</span>
<a class="code" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks,<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"user/tmp/ex1"</span>,
KEY_VALUE,<span class="stringliteral">"some data"</span>, <span class="comment">// set a string value</span>
KEY_END)); <span class="comment">// end of args</span>
<a class="code" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks,<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"user/tmp/ex2"</span>,
KEY_VALUE,<span class="stringliteral">"some data"</span>, <span class="comment">// with a simple value</span>
KEY_MODE,0777, <span class="comment">// permissions</span>
KEY_END)); <span class="comment">// end of args</span>
<a class="code" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks,<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"user/tmp/ex4"</span>,
KEY_TYPE,KEY_TYPE_BINARY, <span class="comment">// key type</span>
KEY_SIZE,7, <span class="comment">// assume binary length 7</span>
KEY_VALUE,<span class="stringliteral">"some data"</span>, <span class="comment">// value that will be truncated in 7 bytes</span>
KEY_COMMENT,<span class="stringliteral">"value is truncated"</span>,
KEY_OWNER,<span class="stringliteral">"root"</span>, <span class="comment">// owner (not uid) is root</span>
KEY_UID,0, <span class="comment">// root uid</span>
KEY_END)); <span class="comment">// end of args</span>
<a class="code" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks,<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"user/tmp/ex5"</span>,
KEY_TYPE,
KEY_TYPE_DIR | KEY_TYPE_BINARY,<span class="comment">// dir key with a binary value</span>
KEY_SIZE,7,
KEY_VALUE,<span class="stringliteral">"some data"</span>, <span class="comment">// value that will be truncated in 7 bytes</span>
KEY_COMMENT,<span class="stringliteral">"value is truncated"</span>,
KEY_OWNER,<span class="stringliteral">"root"</span>, <span class="comment">// owner (not uid) is root</span>
KEY_UID,0, <span class="comment">// root uid</span>
KEY_END)); <span class="comment">// end of args</span>
<a class="code" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel</a>(ks);
</pre></div></dd></dl>
<p>The reference counter (see <a class="el" href="group__key.html#ga4aabc4272506dd63161db2bbb42de8ae">keyGetRef()</a>) will be initialized with 0, that means a subsequent call of <a class="el" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> will delete the key. If you append the key to a keyset the reference counter will be incremented by one (see keyInc()) and the key can't be be deleted by a <a class="el" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a>.</p>
<div class="fragment"><pre class="fragment">Key *k = <a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0); <span class="comment">// ref counter 0</span>
<a class="code" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks, k); <span class="comment">// ref counter of key 1</span>
<a class="code" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel</a>(ks); <span class="comment">// key will be deleted with keyset</span>
*
</pre></div><p>If you increment only by one with keyInc() the same as said above is valid:</p>
<div class="fragment"><pre class="fragment">Key *k = <a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0); <span class="comment">// ref counter 0</span>
<a class="code" href="group__key.html#ga6970a6f254d67af7e39f8e469bb162f1">keyIncRef</a>(k); <span class="comment">// ref counter of key 1</span>
<a class="code" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel</a>(k); <span class="comment">// has no effect</span>
<a class="code" href="group__key.html#ga2c6433ca22109e4e141946057eccb283">keyDecRef</a>(k); <span class="comment">// ref counter back to 0</span>
<a class="code" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel</a>(k); <span class="comment">// key is now deleted</span>
*
</pre></div><p>If you add the key to more keySets:</p>
<div class="fragment"><pre class="fragment">Key *k = <a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0); <span class="comment">// ref counter 0</span>
<a class="code" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks1, k); <span class="comment">// ref counter of key 1</span>
<a class="code" href="group__keyset.html#gaa5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks2, k); <span class="comment">// ref counter of key 2</span>
<a class="code" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel</a>(ks1); <span class="comment">// ref counter of key 1</span>
<a class="code" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel</a>(ks2); <span class="comment">// k is now deleted</span>
*
</pre></div><p>or use keyInc() more than once:</p>
<div class="fragment"><pre class="fragment">Key *k = <a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0); <span class="comment">// ref counter 0</span>
<a class="code" href="group__key.html#ga6970a6f254d67af7e39f8e469bb162f1">keyIncRef</a>(k); <span class="comment">// ref counter of key 1</span>
<a class="code" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (k); <span class="comment">// has no effect</span>
<a class="code" href="group__key.html#ga6970a6f254d67af7e39f8e469bb162f1">keyIncRef</a>(k); <span class="comment">// ref counter of key 2</span>
<a class="code" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (k); <span class="comment">// has no effect</span>
<a class="code" href="group__key.html#ga2c6433ca22109e4e141946057eccb283">keyDecRef</a>(k); <span class="comment">// ref counter of key 1</span>
<a class="code" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (k); <span class="comment">// has no effect</span>
<a class="code" href="group__key.html#ga2c6433ca22109e4e141946057eccb283">keyDecRef</a>(k); <span class="comment">// ref counter is now 0</span>
<a class="code" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (k); <span class="comment">// k is now deleted</span>
*
</pre></div><p>they key won't be deleted by a <a class="el" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> as long refcounter is not 0.</p>
<p>The key's sync bit will always be set for any call, except: </p>
<div class="fragment"><pre class="fragment">Key *k = <a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0);
<span class="comment">// keyNeedSync() will be false</span>
</pre></div><dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>keyName</em> </td><td>a valid name to the key, or NULL to get a simple initialized, but really empty, object </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> </dd></dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>a pointer to a new allocated and initialized Key object, or NULL if an invalid <code>keyName</code> was passed (see <a class="el" href="group__keyname.html#ga7699091610e7f3f43d2949514a4b35d9">keySetName()</a>). </dd></dl>
</div>
</div>
</div>
<hr size="1"/><address style="text-align: right;"><small>Generated on 8 Nov 2009 for Elektra Projekt by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.1 </small></address>
</body>
</html>
