doc/elektra-api/html/group__key.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html><head><meta http-equiv="Content-Type" content="text/html;charset=UTF-8">
   3 <title>Elektra Projekt: Key :: Basic Methods</title>
   4 <link href="doxygen.css" rel="stylesheet" type="text/css">
   5 <link href="tabs.css" rel="stylesheet" type="text/css">
   6 </head><body>
   7 <!-- Generated by Doxygen 1.5.6 -->
   8 <div class="navigation" id="top">
   9   <div class="tabs">
  10     <ul>
  11       <li><a href="index.html"><span>Main&nbsp;Page</span></a></li>
  12       <li><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
  13       <li><a href="modules.html"><span>Modules</span></a></li>
  14     </ul>
  15   </div>
  16 </div>
  17 <div class="contents">
  18 <h1>Key :: Basic Methods</h1>Key construction and initialization methods.
  19 <a href="#_details">More...</a><table border="0" cellpadding="0" cellspacing="0">
  20 <tr><td></td></tr>
  21 <tr><td colspan="2"><br><h2>Functions</h2></td></tr>
  22 <tr><td class="memItemLeft" nowrap align="right" valign="top">Key *&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a> (const char *keyName,...)</td></tr>
  23
  24 <tr><td class="memItemLeft" nowrap align="right" valign="top">Key *&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__key.html#ge6ec6a60cc4b8c1463fa08623d056ce3">keyDup</a> (const Key *source)</td></tr>
  25
  26 <tr><td class="memItemLeft" nowrap align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__key.html#g6a12cbbe656a1ad9f41b8c681d7a2f92">keyCopy</a> (Key *dest, const Key *source)</td></tr>
  27
  28 <tr><td class="memItemLeft" nowrap align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (Key *key)</td></tr>
  29
  30 <tr><td class="memItemLeft" nowrap align="right" valign="top">ssize_t&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__key.html#g6970a6f254d67af7e39f8e469bb162f1">keyIncRef</a> (Key *key)</td></tr>
  31
  32 <tr><td class="memItemLeft" nowrap align="right" valign="top">ssize_t&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__key.html#g2c6433ca22109e4e141946057eccb283">keyDecRef</a> (Key *key)</td></tr>
  33
  34 <tr><td class="memItemLeft" nowrap align="right" valign="top">ssize_t&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__key.html#g4aabc4272506dd63161db2bbb42de8ae">keyGetRef</a> (const Key *key)</td></tr>
  35
  36 </table>
  37 <hr><a name="_details"></a><h2>Detailed Description</h2>
  38 Key construction and initialization methods.
  39 <p>
  40 To use them: <div class="fragment"><pre class="fragment"><span class="preprocessor">#include &lt;kdb.h&gt;</span>
  41 </pre></div><p>
  42 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:<ul>
  43 <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#gb92003db4b938594df48807c16766bf7">Data type </a></li><li><a class="el" href="group__keyvalue.html#gfb89735689929ff717cc9f2d0d0b46a2">Key comment </a></li><li><a class="el" href="group__keyname.html#g6d612841c829a638a8fbbbd4a31cc54a">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>
  44 <p>
  45 Described here the methods to allocate and free the key. <hr><h2>Function Documentation</h2>
  46 <a class="anchor" name="g6a12cbbe656a1ad9f41b8c681d7a2f92"></a><!-- doxytag: member="key.c::keyCopy" ref="g6a12cbbe656a1ad9f41b8c681d7a2f92" args="(Key *dest, const Key *source)" -->
  47 <div class="memitem">
  48 <div class="memproto">
  49       <table class="memname">
  50         <tr>
  51           <td class="memname">int keyCopy           </td>
  52           <td>(</td>
  53           <td class="paramtype">Key *&nbsp;</td>
  54           <td class="paramname"> <em>dest</em>, </td>
  55         </tr>
  56         <tr>
  57           <td class="paramkey"></td>
  58           <td></td>
  59           <td class="paramtype">const Key *&nbsp;</td>
  60           <td class="paramname"> <em>source</em></td><td>&nbsp;</td>
  61         </tr>
  62         <tr>
  63           <td></td>
  64           <td>)</td>
  65           <td></td><td></td><td></td>
  66         </tr>
  67       </table>
  68 </div>
  69 <div class="memdoc">
  70
  71 <p>
  72 Copy or Clear a key.<p>
  73 Most often you may prefer <a class="el" href="group__key.html#ge6ec6a60cc4b8c1463fa08623d056ce3">keyDup()</a> which allocates a new key and returns a duplication of another key.<p>
  74 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>
  75 <div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> h (Key *k)
  76 {
  77         <span class="comment">// receive key c</span>
  78         <a class="code" href="group__key.html#g6a12cbbe656a1ad9f41b8c681d7a2f92">keyCopy</a> (k, c);
  79         <span class="comment">// the caller will see the changed key k</span>
  80 }
  81 </pre></div><p>
  82 The reference counter will not change for the destination key. Affiliation to keysets are also not affected.<p>
  83 When you pass a NULL-pointer as source the data of dest will be cleaned completely and you get a fresh dest key.<p>
  84 <div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> g (Key *k)
  85 {
  86         <a class="code" href="group__key.html#g6a12cbbe656a1ad9f41b8c681d7a2f92">keyCopy</a> (k, 0);
  87         <span class="comment">// k is now an empty and fresh key</span>
  88 }
  89 </pre></div><p>
  90 <dl compact><dt><b>Parameters:</b></dt><dd>
  91   <table border="0" cellspacing="2" cellpadding="0">
  92     <tr><td valign="top"></td><td valign="top"><em>dest</em>&nbsp;</td><td>the key which will be written to </td></tr>
  93     <tr><td valign="top"></td><td valign="top"><em>source</em>&nbsp;</td><td>the key which should be copied or NULL to clean the destination key</td></tr>
  94   </table>
  95 </dl>
  96 <dl class="return" compact><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. <p>
  97 0 when dest was cleaned <p>
  98 1 when source was successfully copied </dd></dl>
  99 <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__key.html#ge6ec6a60cc4b8c1463fa08623d056ce3">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>
 100
 101 </div>
 102 </div><p>
 103 <a class="anchor" name="g2c6433ca22109e4e141946057eccb283"></a><!-- doxytag: member="key.c::keyDecRef" ref="g2c6433ca22109e4e141946057eccb283" args="(Key *key)" -->
 104 <div class="memitem">
 105 <div class="memproto">
 106       <table class="memname">
 107         <tr>
 108           <td class="memname">ssize_t keyDecRef           </td>
 109           <td>(</td>
 110           <td class="paramtype">Key *&nbsp;</td>
 111           <td class="paramname"> <em>key</em>          </td>
 112           <td>&nbsp;)&nbsp;</td>
 113           <td></td>
 114         </tr>
 115       </table>
 116 </div>
 117 <div class="memdoc">
 118
 119 <p>
 120 Decrement the viability of a key object.<p>
 121 The reference counter can't be decremented once it reached 0. In that situation nothing will happen and 0 will be returned.<p>
 122 <dl class="return" compact><dt><b>Returns:</b></dt><dd>the value of the new reference counter <p>
 123 -1 on null pointer <p>
 124 0 when the key is ready to be freed </dd></dl>
 125 <dl compact><dt><b>Parameters:</b></dt><dd>
 126   <table border="0" cellspacing="2" cellpadding="0">
 127     <tr><td valign="top"></td><td valign="top"><em>key</em>&nbsp;</td><td>the key object to work with </td></tr>
 128   </table>
 129 </dl>
 130 <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__key.html#g4aabc4272506dd63161db2bbb42de8ae">keyGetRef()</a>, <a class="el" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a>, <a class="el" href="group__key.html#g6970a6f254d67af7e39f8e469bb162f1">keyIncRef()</a> </dd></dl>
 131
 132 </div>
 133 </div><p>
 134 <a class="anchor" name="g3df95bbc2494e3e6703ece5639be5bb1"></a><!-- doxytag: member="key.c::keyDel" ref="g3df95bbc2494e3e6703ece5639be5bb1" args="(Key *key)" -->
 135 <div class="memitem">
 136 <div class="memproto">
 137       <table class="memname">
 138         <tr>
 139           <td class="memname">int keyDel           </td>
 140           <td>(</td>
 141           <td class="paramtype">Key *&nbsp;</td>
 142           <td class="paramname"> <em>key</em>          </td>
 143           <td>&nbsp;)&nbsp;</td>
 144           <td></td>
 145         </tr>
 146       </table>
 147 </div>
 148 <div class="memdoc">
 149
 150 <p>
 151 A destructor for Key objects.<p>
 152 Every key created by <a class="el" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a> must be deleted with <a class="el" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a>.<p>
 153 It is save to delete keys which are in a keyset, the number of references will be returned then.<p>
 154 It is save to delete a nullpointer, -1 will be returned then.<p>
 155 <dl compact><dt><b>Parameters:</b></dt><dd>
 156   <table border="0" cellspacing="2" cellpadding="0">
 157     <tr><td valign="top"></td><td valign="top"><em>key</em>&nbsp;</td><td>the key object to delete </td></tr>
 158   </table>
 159 </dl>
 160 <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a>, keyInc(), <a class="el" href="group__key.html#g4aabc4272506dd63161db2bbb42de8ae">keyGetRef()</a> </dd></dl>
 161 <dl class="return" compact><dt><b>Returns:</b></dt><dd>the value of the reference counter if the key is within keyset(s) <p>
 162 0 when the key was freed <p>
 163 -1 on null pointers </dd></dl>
 164
 165 </div>
 166 </div><p>
 167 <a class="anchor" name="ge6ec6a60cc4b8c1463fa08623d056ce3"></a><!-- doxytag: member="key.c::keyDup" ref="ge6ec6a60cc4b8c1463fa08623d056ce3" args="(const Key *source)" -->
 168 <div class="memitem">
 169 <div class="memproto">
 170       <table class="memname">
 171         <tr>
 172           <td class="memname">Key* keyDup           </td>
 173           <td>(</td>
 174           <td class="paramtype">const Key *&nbsp;</td>
 175           <td class="paramname"> <em>source</em>          </td>
 176           <td>&nbsp;)&nbsp;</td>
 177           <td></td>
 178         </tr>
 179       </table>
 180 </div>
 181 <div class="memdoc">
 182
 183 <p>
 184 Return a duplicate of a key.<p>
 185 Memory will be allocated as needed for dynamic properties.<p>
 186 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#g3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> will delete the key.<p>
 187 <div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> f (<span class="keyword">const</span> Key * source)
 188 {
 189         Key * dup = <a class="code" href="group__key.html#ge6ec6a60cc4b8c1463fa08623d056ce3">keyDup</a> (source);
 190         <span class="comment">// work with duplicate</span>
 191         <a class="code" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (dup);
 192         <span class="comment">// everything related to dup is freed</span>
 193         <span class="comment">// and source is unchanged</span>
 194 }
 195 </pre></div><p>
 196 Like for a new key after <a class="el" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a> a subsequent <a class="el" href="group__keyset.html#g21eb9c3a14a604ee3a8bdc779232e7b7">ksAppend()</a> makes a KeySet to take care of the lifecycle of the key.<p>
 197 <div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> g (<span class="keyword">const</span> Key * source, KeySet * ks)
 198 {
 199         Key * dup = <a class="code" href="group__key.html#ge6ec6a60cc4b8c1463fa08623d056ce3">keyDup</a> (source);
 200         <span class="comment">// work with duplicate</span>
 201         <a class="code" href="group__keyset.html#ga5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a> (ks, dup);
 202         <span class="comment">// ksDel(ks) will also free the duplicate</span>
 203         <span class="comment">// source remains unchanged.</span>
 204 }
 205 </pre></div><p>
 206 Duplication of keys should be preferred to <a class="el" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">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>
 207 <dl compact><dt><b>Parameters:</b></dt><dd>
 208   <table border="0" cellspacing="2" cellpadding="0">
 209     <tr><td valign="top"></td><td valign="top"><em>source</em>&nbsp;</td><td>has to be an initializised source Key </td></tr>
 210   </table>
 211 </dl>
 212 <dl class="return" compact><dt><b>Returns:</b></dt><dd>0 failure or on NULL pointer <p>
 213 a fully copy of source on success </dd></dl>
 214 <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__keyset.html#g21eb9c3a14a604ee3a8bdc779232e7b7">ksAppend()</a>, <a class="el" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> <p>
 215 keyClear(), <a class="el" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a> </dd></dl>
 216
 217 </div>
 218 </div><p>
 219 <a class="anchor" name="g4aabc4272506dd63161db2bbb42de8ae"></a><!-- doxytag: member="key.c::keyGetRef" ref="g4aabc4272506dd63161db2bbb42de8ae" args="(const Key *key)" -->
 220 <div class="memitem">
 221 <div class="memproto">
 222       <table class="memname">
 223         <tr>
 224           <td class="memname">ssize_t keyGetRef           </td>
 225           <td>(</td>
 226           <td class="paramtype">const Key *&nbsp;</td>
 227           <td class="paramname"> <em>key</em>          </td>
 228           <td>&nbsp;)&nbsp;</td>
 229           <td></td>
 230         </tr>
 231       </table>
 232 </div>
 233 <div class="memdoc">
 234
 235 <p>
 236 Return how many references the key has.<p>
 237 The references will be incremented when <a class="el" href="group__keyset.html#ga5a1d467a4d71041edce68ea7748ce45">ksAppendKey()</a> or <a class="el" href="group__keyset.html#g21eb9c3a14a604ee3a8bdc779232e7b7">ksAppend()</a> uses the key and will be decremented when <a class="el" href="group__keyset.html#ge42530b04defb772059de0600159cf69">ksPop()</a> is used.<p>
 238 <a class="el" href="group__key.html#ge6ec6a60cc4b8c1463fa08623d056ce3">keyDup()</a> will reset the references for dupped key.<p>
 239 For your own applications you can use <a class="el" href="group__key.html#g6970a6f254d67af7e39f8e469bb162f1">keyIncRef()</a> and keyDelRef() for reference counting. Keys with zero references will be deleted when using <a class="el" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a>.<p>
 240 <dl compact><dt><b>Parameters:</b></dt><dd>
 241   <table border="0" cellspacing="2" cellpadding="0">
 242     <tr><td valign="top"></td><td valign="top"><em>key</em>&nbsp;</td><td>the key object to work with </td></tr>
 243   </table>
 244 </dl>
 245 <dl class="return" compact><dt><b>Returns:</b></dt><dd>the number of references <p>
 246 -1 on null pointer </dd></dl>
 247 <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__key.html#g6970a6f254d67af7e39f8e469bb162f1">keyIncRef()</a> and <a class="el" href="group__key.html#g2c6433ca22109e4e141946057eccb283">keyDecRef()</a> </dd></dl>
 248
 249 </div>
 250 </div><p>
 251 <a class="anchor" name="g6970a6f254d67af7e39f8e469bb162f1"></a><!-- doxytag: member="key.c::keyIncRef" ref="g6970a6f254d67af7e39f8e469bb162f1" args="(Key *key)" -->
 252 <div class="memitem">
 253 <div class="memproto">
 254       <table class="memname">
 255         <tr>
 256           <td class="memname">ssize_t keyIncRef           </td>
 257           <td>(</td>
 258           <td class="paramtype">Key *&nbsp;</td>
 259           <td class="paramname"> <em>key</em>          </td>
 260           <td>&nbsp;)&nbsp;</td>
 261           <td></td>
 262         </tr>
 263       </table>
 264 </div>
 265 <div class="memdoc">
 266
 267 <p>
 268 Increment the viability of a key object.<p>
 269 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#g3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a>.<p>
 270 <div class="fragment"><pre class="fragment">Key *k;
 271 keyInc (k);
 272 function_that_keyDec(k);
 273 <span class="comment">// work with k</span>
 274 <a class="code" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (k); <span class="comment">// now really free it</span>
 275 </pre></div><p>
 276 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>
 277 <dl class="return" compact><dt><b>Returns:</b></dt><dd>the value of the new reference counter <p>
 278 -1 on null pointer <p>
 279 SSIZE_MAX when maximum exceeded </dd></dl>
 280 <dl compact><dt><b>Parameters:</b></dt><dd>
 281   <table border="0" cellspacing="2" cellpadding="0">
 282     <tr><td valign="top"></td><td valign="top"><em>key</em>&nbsp;</td><td>the key object to work with </td></tr>
 283   </table>
 284 </dl>
 285 <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__key.html#g4aabc4272506dd63161db2bbb42de8ae">keyGetRef()</a>, <a class="el" href="group__key.html#g2c6433ca22109e4e141946057eccb283">keyDecRef()</a>, <a class="el" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> </dd></dl>
 286
 287 </div>
 288 </div><p>
 289 <a class="anchor" name="gf6893c038b3ebee90c73a9ea8356bebf"></a><!-- doxytag: member="key.c::keyNew" ref="gf6893c038b3ebee90c73a9ea8356bebf" args="(const char *keyName,...)" -->
 290 <div class="memitem">
 291 <div class="memproto">
 292       <table class="memname">
 293         <tr>
 294           <td class="memname">Key* keyNew           </td>
 295           <td>(</td>
 296           <td class="paramtype">const char *&nbsp;</td>
 297           <td class="paramname"> <em>keyName</em>, </td>
 298         </tr>
 299         <tr>
 300           <td class="paramkey"></td>
 301           <td></td>
 302           <td class="paramtype">&nbsp;</td>
 303           <td class="paramname"> <em>...</em></td><td>&nbsp;</td>
 304         </tr>
 305         <tr>
 306           <td></td>
 307           <td>)</td>
 308           <td></td><td></td><td></td>
 309         </tr>
 310       </table>
 311 </div>
 312 <div class="memdoc">
 313
 314 <p>
 315 A practical way to fully create a Key object in one step.<p>
 316 This function tries to mimic the C++ way for constructors.<p>
 317 To just get a key object, simple do: <div class="fragment"><pre class="fragment">Key *k = <a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0);
 318 <span class="comment">// work with it</span>
 319 <a class="code" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (k);
 320 </pre></div><p>
 321 If you want the key object to contain a name, value, comment and other meta info read on.<p>
 322 <dl class="note" compact><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#ge6ec6a60cc4b8c1463fa08623d056ce3">keyDup()</a> the key.</dd></dl>
 323 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#gf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a> and <a class="el" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">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>
 324 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#gf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a> which Key attribute comes next.<p>
 325 The simplest and minimum way to use it is with no tags, only a key name: <div class="fragment"><pre class="fragment">Key *nullKey,*emptyNamedKey;
 326
 327 <span class="comment">// Create a key that has no name, is completely empty, but is initialized</span>
 328 nullKey=<a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0);
 329 <a class="code" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (nullKey);
 330
 331 <span class="comment">// Is the same as above</span>
 332 nullKey=<a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">""</span>, KEY_END);
 333 <a class="code" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (nullKey);
 334
 335 <span class="comment">// Create and initialize a key with a name and nothing else</span>
 336 emptyNamedKey=<a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"user/some/example"</span>,KEY_END);
 337 <a class="code" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (emptyNamedKey);
 338 </pre></div><p>
 339 <a class="el" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a> allocates memory for a key object and cleans everything up. After that, it processes the given argument list.<p>
 340 The Key attribute tags are the following:<ul>
 341 <li>keyswitch_t::KEY_TYPE <br>
 342  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#g622bde1eb0e0c4994728331326340ef2">keySetString()</a> or <a class="el" href="group__keyvalue.html#ga50a5358fd328d373a45f395fa1b99e7">keySetBinary()</a> regarding to <a class="el" href="group__keytest.html#gea7670778abd07fee0fe8ac12a149190">keyIsString()</a> or <a class="el" href="group__keytest.html#g9526b371087564e43e3dff8ad0dac949">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>
 343  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>
 344  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>
 345  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#gb5f284f5ecd261e0a290095f50ba1af7">keySetUID()</a> and <a class="el" href="group__keymeta.html#g9e3d0fb3f7ba906e067727b9155d22e3">keySetGID()</a>.</li><li>keyswitch_t::KEY_MODE <br>
 346  Next parameter is taken as mode permissions (mode_t) to the key. See <a class="el" href="group__keymeta.html#g8803037e35b9da1ce492323a88ff6bc3">keySetMode()</a>.</li><li>keyswitch_t::KEY_DIR <br>
 347  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#gae575bd86a628a15ee45baa860522e75">keySetDir()</a>.</li><li>keyswitch_t::KEY_OWNER <br>
 348  Next parameter is the owner. See <a class="el" href="group__keyname.html#ga899d9f0251cb98a89761ef112910eca">keySetOwner()</a>.</li><li>keyswitch_t::KEY_COMMENT <br>
 349  Next parameter is a comment. See <a class="el" href="group__keyvalue.html#g8863a877a84fa46e6017fe72e49b89c1">keySetComment()</a>.</li><li>keyswitch_t::KEY_REMOVE <br>
 350  Mark the key to be removed instead of set it. See <a class="el" href="group__keymeta.html#g6e14e5f1de26e1318100631a149f2984">keyRemove()</a>.</li><li>keyswitch_t::KEY_STAT <br>
 351  Mark the key to be stated instead of get it. See <a class="el" href="group__keymeta.html#gb8189add5e562bdb148675ee595bd95b">keyStat()</a>.</li><li>keyswitch_t::KEY_END <br>
 352  Must be the last parameter passed to <a class="el" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a>. It is always required, unless the <code>keyName</code> is 0.</li></ul>
 353 <p>
 354 <dl class="user" compact><dt><b>Example:</b></dt><dd><div class="fragment"><pre class="fragment">KeySet *ks=<a class="code" href="group__keyset.html#g671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew</a>(0);
 355
 356 <a class="code" href="group__keyset.html#ga5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks,<a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0));       <span class="comment">// an empty key</span>
 357
 358 <a class="code" href="group__keyset.html#ga5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks,<a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"user/sw"</span>,              <span class="comment">// the name of the key</span>
 359         KEY_END));                      <span class="comment">// no more args</span>
 360
 361 <a class="code" href="group__keyset.html#ga5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks,<a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"user/tmp/ex1"</span>,
 362         KEY_VALUE,<span class="stringliteral">"some data"</span>,          <span class="comment">// set a string value</span>
 363         KEY_END));                      <span class="comment">// end of args</span>
 364
 365 <a class="code" href="group__keyset.html#ga5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks,<a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"user/tmp/ex2"</span>,
 366         KEY_VALUE,<span class="stringliteral">"some data"</span>,          <span class="comment">// with a simple value</span>
 367         KEY_MODE,0777,                  <span class="comment">// permissions</span>
 368         KEY_END));                      <span class="comment">// end of args</span>
 369
 370 <a class="code" href="group__keyset.html#ga5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks,<a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"user/tmp/ex4"</span>,
 371         KEY_TYPE,KEY_TYPE_BINARY,       <span class="comment">// key type</span>
 372         KEY_SIZE,7,                     <span class="comment">// assume binary length 7</span>
 373         KEY_VALUE,<span class="stringliteral">"some data"</span>,          <span class="comment">// value that will be truncated in 7 bytes</span>
 374         KEY_COMMENT,<span class="stringliteral">"value is truncated"</span>,
 375         KEY_OWNER,<span class="stringliteral">"root"</span>,               <span class="comment">// owner (not uid) is root</span>
 376         KEY_UID,0,                      <span class="comment">// root uid</span>
 377         KEY_END));                      <span class="comment">// end of args</span>
 378
 379 <a class="code" href="group__keyset.html#ga5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks,<a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"user/tmp/ex5"</span>,
 380         KEY_TYPE,
 381                 KEY_TYPE_DIR | KEY_TYPE_BINARY,<span class="comment">// dir key with a binary value</span>
 382         KEY_SIZE,7,
 383         KEY_VALUE,<span class="stringliteral">"some data"</span>,          <span class="comment">// value that will be truncated in 7 bytes</span>
 384         KEY_COMMENT,<span class="stringliteral">"value is truncated"</span>,
 385         KEY_OWNER,<span class="stringliteral">"root"</span>,               <span class="comment">// owner (not uid) is root</span>
 386         KEY_UID,0,                      <span class="comment">// root uid</span>
 387         KEY_END));                      <span class="comment">// end of args</span>
 388
 389 <a class="code" href="group__keyset.html#g27e5c16473b02a422238c8d970db7ac8">ksDel</a>(ks);
 390 </pre></div></dd></dl>
 391 The reference counter (see <a class="el" href="group__key.html#g4aabc4272506dd63161db2bbb42de8ae">keyGetRef()</a>) will be initialized with 0, that means a subsequent call of <a class="el" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">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#g3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a>.<p>
 392 <div class="fragment"><pre class="fragment">Key *k = <a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0); <span class="comment">// ref counter 0</span>
 393 <a class="code" href="group__keyset.html#ga5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks, k); <span class="comment">// ref counter of key 1</span>
 394 <a class="code" href="group__keyset.html#g27e5c16473b02a422238c8d970db7ac8">ksDel</a>(ks); <span class="comment">// key will be deleted with keyset</span>
 395  *
 396 </pre></div><p>
 397 If you increment only by one with keyInc() the same as said above is valid:<p>
 398 <div class="fragment"><pre class="fragment">Key *k = <a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0); <span class="comment">// ref counter 0</span>
 399 <a class="code" href="group__key.html#g6970a6f254d67af7e39f8e469bb162f1">keyIncRef</a>(k); <span class="comment">// ref counter of key 1</span>
 400 <a class="code" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel</a>(k);    <span class="comment">// has no effect</span>
 401 <a class="code" href="group__key.html#g2c6433ca22109e4e141946057eccb283">keyDecRef</a>(k); <span class="comment">// ref counter back to 0</span>
 402 <a class="code" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel</a>(k);    <span class="comment">// key is now deleted</span>
 403  *
 404 </pre></div><p>
 405 If you add the key to more keySets:<p>
 406 <div class="fragment"><pre class="fragment">Key *k = <a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0); <span class="comment">// ref counter 0</span>
 407 <a class="code" href="group__keyset.html#ga5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks1, k); <span class="comment">// ref counter of key 1</span>
 408 <a class="code" href="group__keyset.html#ga5a1d467a4d71041edce68ea7748ce45">ksAppendKey</a>(ks2, k); <span class="comment">// ref counter of key 2</span>
 409 <a class="code" href="group__keyset.html#g27e5c16473b02a422238c8d970db7ac8">ksDel</a>(ks1); <span class="comment">// ref counter of key 1</span>
 410 <a class="code" href="group__keyset.html#g27e5c16473b02a422238c8d970db7ac8">ksDel</a>(ks2); <span class="comment">// k is now deleted</span>
 411  *
 412 </pre></div><p>
 413 or use keyInc() more than once:<p>
 414 <div class="fragment"><pre class="fragment">Key *k = <a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0); <span class="comment">// ref counter 0</span>
 415 <a class="code" href="group__key.html#g6970a6f254d67af7e39f8e469bb162f1">keyIncRef</a>(k); <span class="comment">// ref counter of key 1</span>
 416 <a class="code" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (k);   <span class="comment">// has no effect</span>
 417 <a class="code" href="group__key.html#g6970a6f254d67af7e39f8e469bb162f1">keyIncRef</a>(k); <span class="comment">// ref counter of key 2</span>
 418 <a class="code" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (k);   <span class="comment">// has no effect</span>
 419 <a class="code" href="group__key.html#g2c6433ca22109e4e141946057eccb283">keyDecRef</a>(k); <span class="comment">// ref counter of key 1</span>
 420 <a class="code" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (k);   <span class="comment">// has no effect</span>
 421 <a class="code" href="group__key.html#g2c6433ca22109e4e141946057eccb283">keyDecRef</a>(k); <span class="comment">// ref counter is now 0</span>
 422 <a class="code" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (k); <span class="comment">// k is now deleted</span>
 423  *
 424 </pre></div><p>
 425 they key won't be deleted by a <a class="el" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> as long refcounter is not 0.<p>
 426 The key's sync bit will always be set for any call, except: <div class="fragment"><pre class="fragment">Key *k = <a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0);
 427 <span class="comment">// keyNeedSync() will be false</span>
 428 </pre></div><p>
 429 <dl compact><dt><b>Parameters:</b></dt><dd>
 430   <table border="0" cellspacing="2" cellpadding="0">
 431     <tr><td valign="top"></td><td valign="top"><em>keyName</em>&nbsp;</td><td>a valid name to the key, or NULL to get a simple initialized, but really empty, object </td></tr>
 432   </table>
 433 </dl>
 434 <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> </dd></dl>
 435 <dl class="return" compact><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#g7699091610e7f3f43d2949514a4b35d9">keySetName()</a>). </dd></dl>
 436
 437 </div>
 438 </div><p>
 439 </div>
 440 <hr size="1"><address style="text-align: right;"><small>Generated on Tue Jun 30 14:43:54 2009 for Elektra Projekt by&nbsp;
 441 <a href="http://www.doxygen.org/index.html">
 442 <img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.6 </small></address>
 443 </body>
 444 </html>