Git init
[pkgs/e/elektra.git] / doc / elektra-api / html / group__kdb.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: KDB :: Low Level 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>KDB :: Low Level Methods</h1>General methods to access the Key database.  
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">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__kdb.html#g40e35f26cc69bd43ef1b2207f4fa121b">kdbMount</a> (KDB *handle, const Key *mountpoint, const KeySet *config)</td></tr>
23
24 <tr><td class="memItemLeft" nowrap align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__kdb.html#g400ca66a9bdc04ecadb66d84dc06bd55">kdbUnmount</a> (KDB *handle, const Key *mountpoint)</td></tr>
25
26 <tr><td class="memItemLeft" nowrap align="right" valign="top">Key *&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__kdb.html#ga3717146f45e5a9665377c7f5b71e39b">kdbGetMountpoint</a> (KDB *handle, const Key *where)</td></tr>
27
28 <tr><td class="memItemLeft" nowrap align="right" valign="top">KDB *&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__kdb.html#gb7be60c387892d2235907836c5060e1f">kdbOpen</a> ()</td></tr>
29
30 <tr><td class="memItemLeft" nowrap align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__kdb.html#gd9bb8bd3f1296bfa77cc9a1b41b7a859">kdbClose</a> (KDB *handle)</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__kdb.html#g37b44bda1b83bc0144916bf21a86c1b5">kdbGet</a> (KDB *handle, KeySet *returned, Key *parentKey, option_t options)</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__kdb.html#g953cf29721e6000c2516cd6b5d36f571">kdbSet</a> (KDB *handle, KeySet *ks, Key *parentKey, option_t options)</td></tr>
35
36 </table>
37 <hr><a name="_details"></a><h2>Detailed Description</h2>
38 General methods to access the Key database. 
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 The kdb*() class of methods are used to access the storage, to get and set <a class="el" href="group__key.html">Keys </a> or <a class="el" href="group__keyset.html">KeySets </a>.<p>
43 The most important functions are:<ul>
44 <li><a class="el" href="group__kdb.html#gb7be60c387892d2235907836c5060e1f">kdbOpen()</a></li><li><a class="el" href="group__kdb.html#gd9bb8bd3f1296bfa77cc9a1b41b7a859">kdbClose()</a></li><li><a class="el" href="group__kdb.html#g37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a></li><li><a class="el" href="group__kdb.html#g953cf29721e6000c2516cd6b5d36f571">kdbSet()</a></li></ul>
45 <p>
46 The two essential functions for dynamic information about backends are:<ul>
47 <li><a class="el" href="group__kdb.html#ga3717146f45e5a9665377c7f5b71e39b">kdbGetMountpoint()</a></li><li>kdbGetCapability()</li></ul>
48 <p>
49 They use some backend implementation to know the details about how to access the storage. Currently we have this backends:<ul>
50 <li><code>berkeleydb:</code> the keys are stored in a Berkeley DB database, providing very small footprint, speed, and other advantages.</li><li><code>filesys:</code> the key hierarchy and data are saved as plain text files in the filesystem.</li><li><code>ini:</code> the key hierarchy are saved into configuration files. <dl class="see" compact><dt><b>See also:</b></dt><dd><a href="http://www.libelektra.org/Ini">http://www.libelektra.org/Ini</a></dd></dl>
51 </li><li><code>fstab:</code> a reference backend used to interpret the <code>/etc/fstab</code> file as a set of keys under <code>system/filesystems</code> .</li><li><code>gconf:</code> makes Elektra use the GConf daemon to access keys. Only the <code>user/</code> tree is available since GConf is not system wide.</li></ul>
52 <p>
53 Backends are physically a library named <code>/lib/libelektra-{NAME}</code>.so.<p>
54 See <a class="el" href="group__backend.html">writing a new backend </a> for information about how to write a backend.<p>
55 Language binding writers should follow the same rules:<ul>
56 <li>You must relay completely on the backend-dependent methods.</li><li>You may use or reimplement the second set of methods.</li><li>You should completely reimplement in your language the higher lever methods.</li><li>Many methods are just for comfort in C. These methods are marked and need not to be implemented if the binding language has e.g. string operators which can do the operation easily. </li></ul>
57 <hr><h2>Function Documentation</h2>
58 <a class="anchor" name="gd9bb8bd3f1296bfa77cc9a1b41b7a859"></a><!-- doxytag: member="kdb.c::kdbClose" ref="gd9bb8bd3f1296bfa77cc9a1b41b7a859" args="(KDB *handle)" -->
59 <div class="memitem">
60 <div class="memproto">
61       <table class="memname">
62         <tr>
63           <td class="memname">int kdbClose           </td>
64           <td>(</td>
65           <td class="paramtype">KDB *&nbsp;</td>
66           <td class="paramname"> <em>handle</em>          </td>
67           <td>&nbsp;)&nbsp;</td>
68           <td></td>
69         </tr>
70       </table>
71 </div>
72 <div class="memdoc">
73
74 <p>
75 Closes the session with the Key database.<p>
76 You should call this method when you finished your affairs with the key database. You can manipulate Key and KeySet objects also after <a class="el" href="group__kdb.html#gd9bb8bd3f1296bfa77cc9a1b41b7a859">kdbClose()</a>. You must not use any kdb* call afterwards. You can implement <a class="el" href="group__kdb.html#gd9bb8bd3f1296bfa77cc9a1b41b7a859">kdbClose()</a> in the atexit() handler.<p>
77 This is the counterpart of <a class="el" href="group__kdb.html#gb7be60c387892d2235907836c5060e1f">kdbOpen()</a>.<p>
78 The <code>handle</code> parameter will be finalized and all resources associated to it will be freed. After a <a class="el" href="group__kdb.html#gd9bb8bd3f1296bfa77cc9a1b41b7a859">kdbClose()</a>, this <code>handle</code> can't be used anymore, unless it gets initialized again with another call to <a class="el" href="group__kdb.html#gb7be60c387892d2235907836c5060e1f">kdbOpen()</a>.<p>
79 <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kdb.html#gb7be60c387892d2235907836c5060e1f">kdbOpen()</a> </dd></dl>
80 <dl compact><dt><b>Parameters:</b></dt><dd>
81   <table border="0" cellspacing="2" cellpadding="0">
82     <tr><td valign="top"></td><td valign="top"><em>handle</em>&nbsp;</td><td>contains internal information of <a class="el" href="group__kdb.html#gb7be60c387892d2235907836c5060e1f">opened </a> key database </td></tr>
83   </table>
84 </dl>
85 <dl class="return" compact><dt><b>Returns:</b></dt><dd>0 on success <p>
86 -1 on NULL pointer </dd></dl>
87
88 </div>
89 </div><p>
90 <a class="anchor" name="g37b44bda1b83bc0144916bf21a86c1b5"></a><!-- doxytag: member="kdb.c::kdbGet" ref="g37b44bda1b83bc0144916bf21a86c1b5" args="(KDB *handle, KeySet *returned, Key *parentKey, option_t options)" -->
91 <div class="memitem">
92 <div class="memproto">
93       <table class="memname">
94         <tr>
95           <td class="memname">ssize_t kdbGet           </td>
96           <td>(</td>
97           <td class="paramtype">KDB *&nbsp;</td>
98           <td class="paramname"> <em>handle</em>, </td>
99         </tr>
100         <tr>
101           <td class="paramkey"></td>
102           <td></td>
103           <td class="paramtype">KeySet *&nbsp;</td>
104           <td class="paramname"> <em>returned</em>, </td>
105         </tr>
106         <tr>
107           <td class="paramkey"></td>
108           <td></td>
109           <td class="paramtype">Key *&nbsp;</td>
110           <td class="paramname"> <em>parentKey</em>, </td>
111         </tr>
112         <tr>
113           <td class="paramkey"></td>
114           <td></td>
115           <td class="paramtype">option_t&nbsp;</td>
116           <td class="paramname"> <em>options</em></td><td>&nbsp;</td>
117         </tr>
118         <tr>
119           <td></td>
120           <td>)</td>
121           <td></td><td></td><td></td>
122         </tr>
123       </table>
124 </div>
125 <div class="memdoc">
126
127 <p>
128 Retrieve keys in an atomic and universal way, all other kdbGet Functions rely on that one.<p>
129 The <code>returned</code> KeySet must be initialized or may already contain some keys. The new retrieved keys will be appended using <a class="el" href="group__keyset.html#ga5a1d467a4d71041edce68ea7748ce45">ksAppendKey()</a>.<p>
130 In default behaviour (<code>options</code> = 0) it will fully retrieve all keys under the <code>parentKey</code> folder, with all subfolders and their children but not inactive keys or folders.<p>
131 The keyset will not be sorted at first place, but will be marked dirty and sorted afterwards when needed. That could be a subsequent <a class="el" href="group__keyset.html#ga34fc43a081e6b01e4120daa6c112004">ksLookup()</a>, <a class="el" href="group__keyset.html#gd2e30fb6d4739d917c5abb2ac2f9c1a1">ksLookupByName()</a> or <a class="el" href="group__kdb.html#g953cf29721e6000c2516cd6b5d36f571">kdbSet()</a>. See <a class="el" href="group__keyset.html#g023554d395ccf2319a3807b8b5d2530c">ksSort()</a> on that issue.<p>
132 The behaviour can be fine-tuned with options in various ways to make <a class="el" href="group__kdb.html#g37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> more comfortable.<h2><a class="anchor" name="kdbgetoption">
133 Options</a></h2>
134 The <code>option</code> is an array of the following ORed flags:<p>
135 <ul>
136 <li><code>option_t::KDB_O_DEL</code> <br>
137  Its often useful to <a class="el" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> the parentKey in the line after <a class="el" href="group__kdb.html#g37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a>. Using this flag, you can just pass a key allocated with <a class="el" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a>, <a class="el" href="group__kdb.html#g37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> will free it for you in the end.</li><li><code>option_t::KDB_O_POP</code> <br>
138  The <code>parentKey</code> itself will always be added to <code>returned</code>. If you only want the children of the parentKey in <code>returned</code>, but not the parentKey itself, use this flag. This is only valid for the first parentKey, the one you passed. The other recursive parentKeys will stay in the keyset. To get only the leaves of the tree, without any parentKey, see option_t::KDB_O_NODIR below.</li><li><code>option_t::KDB_O_NODIR</code> <br>
139  Don't include folders in the <code>returned</code> KeySet, so only keys without subkeys. You can picture it best that you only get the leaves of the tree of keys.</li><li><code>option_t::KDB_O_DIRONLY</code> <br>
140  Put in <code>returned</code> only the folder keys. The resulting KeySet will be only the skeleton of the tree. This option must not be ORed together with KDB_O_DIR.</li><li><code>option_t::KDB_O_NOSTAT</code> <br>
141  Don't stat they keys, whatever <a class="el" href="group__keytest.html#g3908b6511648a950f37cd0005bfea5d5">keyNeedStat()</a> says. That means that also the key value and comment will be retrieved. The flag will result in that all keys in <code>returned</code> don't have <a class="el" href="group__keytest.html#g3908b6511648a950f37cd0005bfea5d5">keyNeedStat()</a> set.</li><li><code>option_t::KDB_O_STATONLY</code> <br>
142  Only stat the keys. It means that key value and comment will not be retrieved. The resulting keys will contain only meta info such as user and group IDs, owner, mode permissions and modification times. You don't need that flag if the keys already have <a class="el" href="group__keytest.html#g3908b6511648a950f37cd0005bfea5d5">keyNeedStat()</a> set. The flag will result in that all keys in <code>returned</code> have <a class="el" href="group__keytest.html#g3908b6511648a950f37cd0005bfea5d5">keyNeedStat()</a> set.</li><li><code>option_t::KDB_O_INACTIVE</code> <br>
143  Will make it not ignore inactive keys, so <code>returned</code> will contain also inactive keys. Inactive keys are those that have names begining with '.' (dot). Please be sure that you know what you are doing, inactive keys must not have any semantics to the application. This flag should only be set in key browsers after explicit user request. You might also get inactive keys when you plan to remove a whole hierarchy.</li><li><code>option_t::KDB_O_SORT</code> <br>
144  Force <code>returned</code> to be <a class="el" href="group__keyset.html#g023554d395ccf2319a3807b8b5d2530c">ksSort()</a>ed. Normally you don't want that the <code>returned</code> is sorted immediately because you might add other keys or go for another <a class="el" href="group__kdb.html#g37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a>. Sorting will take place automatically when needed by <a class="el" href="group__keyset.html#ga34fc43a081e6b01e4120daa6c112004">ksLookup()</a> or <a class="el" href="group__kdb.html#g953cf29721e6000c2516cd6b5d36f571">kdbSet()</a>, also without this option set. But you need to sort the keyset for yourself, when you just iterate over it. If you want to do that, pass this flag at the last <a class="el" href="group__kdb.html#g37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a>.</li><li><code>option_t::KDB_O_NORECURSIVE</code> <br>
145  Dont get the keys recursive. Only receive keys from one folder. This might not work if the backend does not support it. Be prepared for more keys and use <a class="el" href="group__keyset.html#ga34fc43a081e6b01e4120daa6c112004">ksLookup()</a> and avoid static assumptions on how many keys you get.</li></ul>
146 <p>
147 <dl class="user" compact><dt><b>Example:</b></dt><dd><div class="fragment"><pre class="fragment">KDB *handle;
148 KeySet *myConfig;
149 Key *key;
150
151 myConfig=<a class="code" href="group__keyset.html#g671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew</a>(0);
152
153 handle = <a class="code" href="group__kdb.html#gb7be60c387892d2235907836c5060e1f">kdbOpen</a>();
154
155 key=<a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"system/sw/MyApp"</span>,KEY_END);
156 rc=<a class="code" href="group__kdb.html#g37b44bda1b83bc0144916bf21a86c1b5">kdbGet</a>(handle,key, myConfig, 0);
157 <a class="code" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel</a>(key);
158
159 key=<a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"user/sw/MyApp"</span>,KEY_END);
160 rc=<a class="code" href="group__kdb.html#g37b44bda1b83bc0144916bf21a86c1b5">kdbGet</a>(handle,key, myConfig, 0);
161 <a class="code" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel</a>(key);
162
163 <span class="comment">// will sort keyset here</span>
164 key=<a class="code" href="group__keyset.html#gd2e30fb6d4739d917c5abb2ac2f9c1a1">ksLookupByName</a>(myConfig,<span class="stringliteral">"/sw/MyApp/key"</span>, 0);
165 <span class="comment">// check if key is not 0 and work with it...</span>
166
167 <a class="code" href="group__keyset.html#g27e5c16473b02a422238c8d970db7ac8">ksDel</a> (myConfig); <span class="comment">// delete the in-memory configuration</span>
168
169
170 <span class="comment">// maybe you want kdbSet() myConfig here</span>
171
172 <a class="code" href="group__kdb.html#gd9bb8bd3f1296bfa77cc9a1b41b7a859">kdbClose</a>(handle); <span class="comment">// no more affairs with the key database.</span>
173 </pre></div></dd></dl>
174 <h2><a class="anchor" name="kdbgetdetail">
175 Details</a></h2>
176 When no backend could be found (e.g. no backend mounted) the default backend will be used.<p>
177 If you pass a NULL pointer as handle and/or returned <a class="el" href="group__kdb.html#g37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> will return -1 and do nothing but <a class="el" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> the parentKey when requested and not a NULL pointer.<p>
178 If you pass NULL as parentKey the root keys of all namespaces will be appended to returned.<p>
179 For every directory key (<a class="el" href="group__keytest.html#gc0a10c602d52a35f81347e8a32312017">keyIsDir()</a>) the appropriate backend will be chosen and keys in it will be requested.<p>
180 If any backend reports an failure the recursive getting of keys will be stopped. Backends only report failure when they are not able to get keys for any problems.<p>
181 <dl compact><dt><b>Parameters:</b></dt><dd>
182   <table border="0" cellspacing="2" cellpadding="0">
183     <tr><td valign="top"></td><td valign="top"><em>handle</em>&nbsp;</td><td>contains internal information of <a class="el" href="group__kdb.html#gb7be60c387892d2235907836c5060e1f">opened </a> key database </td></tr>
184     <tr><td valign="top"></td><td valign="top"><em>parentKey</em>&nbsp;</td><td>parent key or NULL to get the root keys </td></tr>
185     <tr><td valign="top"></td><td valign="top"><em>returned</em>&nbsp;</td><td>the (pre-initialized) KeySet returned with all keys found </td></tr>
186     <tr><td valign="top"></td><td valign="top"><em>options</em>&nbsp;</td><td>ORed options to control approaches </td></tr>
187   </table>
188 </dl>
189 <dl class="see" compact><dt><b>See also:</b></dt><dd>option_t <p>
190 <a class="el" href="group__kdbhighlevel.html">kdb higher level Methods </a> that rely on <a class="el" href="group__kdb.html#g37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> <p>
191 <a class="el" href="group__keyset.html#gd2e30fb6d4739d917c5abb2ac2f9c1a1">ksLookupByName()</a>, ksLookupByString() for powerful lookups after the KeySet was retrieved <p>
192 commandList() code in <a class="el" href="group__kdb.html" title="General methods to access the Key database.">KDB :: Low Level Methods</a> command for usage example <p>
193 commandEdit() code in <a class="el" href="group__kdb.html" title="General methods to access the Key database.">KDB :: Low Level Methods</a> command for usage example <p>
194 commandExport() code in <a class="el" href="group__kdb.html" title="General methods to access the Key database.">KDB :: Low Level Methods</a> command for usage example </dd></dl>
195 <dl class="return" compact><dt><b>Returns:</b></dt><dd>number of keys contained by <code>returned</code> <p>
196 -1 on failure </dd></dl>
197
198 </div>
199 </div><p>
200 <a class="anchor" name="ga3717146f45e5a9665377c7f5b71e39b"></a><!-- doxytag: member="kdb.c::kdbGetMountpoint" ref="ga3717146f45e5a9665377c7f5b71e39b" args="(KDB *handle, const Key *where)" -->
201 <div class="memitem">
202 <div class="memproto">
203       <table class="memname">
204         <tr>
205           <td class="memname">Key* kdbGetMountpoint           </td>
206           <td>(</td>
207           <td class="paramtype">KDB *&nbsp;</td>
208           <td class="paramname"> <em>handle</em>, </td>
209         </tr>
210         <tr>
211           <td class="paramkey"></td>
212           <td></td>
213           <td class="paramtype">const Key *&nbsp;</td>
214           <td class="paramname"> <em>where</em></td><td>&nbsp;</td>
215         </tr>
216         <tr>
217           <td></td>
218           <td>)</td>
219           <td></td><td></td><td></td>
220         </tr>
221       </table>
222 </div>
223 <div class="memdoc">
224
225 <p>
226 Lookup a mountpoint in a handle for a specific key.<p>
227 Will return a key representing the mountpoint or null if there is no appropriate mountpoint e.g. its the root mountpoint.<p>
228 Together with kdbGetCapability() the two essential informations about mounted backends.<p>
229 <dl class="user" compact><dt><b>Example:</b></dt><dd><div class="fragment"><pre class="fragment">Key * key = <a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a> (<span class="stringliteral">"system/template"</span>);
230 KDB * handle = <a class="code" href="group__kdb.html#gb7be60c387892d2235907836c5060e1f">kdbOpen</a>();
231 Key *mountpoint=0;
232 mountpoint=<a class="code" href="group__kdb.html#ga3717146f45e5a9665377c7f5b71e39b">kdbGetMountpoint</a>(handle, key);
233
234 printf(<span class="stringliteral">"The library I am using is %s mounted in %s\n"</span>,
235         <a class="code" href="group__keyvalue.html#g6f29609c5da53c6dc26a98678d5752af">keyValue</a>(mountpoint),
236         <a class="code" href="group__keyname.html#g8e805c726a60da921d3736cda7813513">keyName</a>(mountpoint));
237 <a class="code" href="group__kdb.html#gd9bb8bd3f1296bfa77cc9a1b41b7a859">kdbClose</a> (handle);
238 <a class="code" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel</a> (key);
239 </pre></div></dd></dl>
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>handle</em>&nbsp;</td><td>is the data structure, where the mounted directories are saved. </td></tr>
243     <tr><td valign="top"></td><td valign="top"><em>where</em>&nbsp;</td><td>the key, that should be looked up. </td></tr>
244   </table>
245 </dl>
246 <dl class="return" compact><dt><b>Returns:</b></dt><dd>the mountpoint associated with the key </dd></dl>
247
248 </div>
249 </div><p>
250 <a class="anchor" name="g40e35f26cc69bd43ef1b2207f4fa121b"></a><!-- doxytag: member="kdb.c::kdbMount" ref="g40e35f26cc69bd43ef1b2207f4fa121b" args="(KDB *handle, const Key *mountpoint, const KeySet *config)" -->
251 <div class="memitem">
252 <div class="memproto">
253       <table class="memname">
254         <tr>
255           <td class="memname">int kdbMount           </td>
256           <td>(</td>
257           <td class="paramtype">KDB *&nbsp;</td>
258           <td class="paramname"> <em>handle</em>, </td>
259         </tr>
260         <tr>
261           <td class="paramkey"></td>
262           <td></td>
263           <td class="paramtype">const Key *&nbsp;</td>
264           <td class="paramname"> <em>mountpoint</em>, </td>
265         </tr>
266         <tr>
267           <td class="paramkey"></td>
268           <td></td>
269           <td class="paramtype">const KeySet *&nbsp;</td>
270           <td class="paramname"> <em>config</em></td><td>&nbsp;</td>
271         </tr>
272         <tr>
273           <td></td>
274           <td>)</td>
275           <td></td><td></td><td></td>
276         </tr>
277       </table>
278 </div>
279 <div class="memdoc">
280
281 <p>
282 Dynamically mount a single backend.<p>
283 Maps the mountpoint, defined through its name and value, into the global elektra hierachy. If successfull, under the mountpoint another backend will reside.<p>
284 This only works for a single KDB, that means a single thread in a single process. You may want statically mounting by editing system/elektra/mountpoints.<p>
285 If you allocated mountpoint and config first, make sure that you free it! It is ok to free it immediately afterwards.<p>
286 <dl compact><dt><b>Parameters:</b></dt><dd>
287   <table border="0" cellspacing="2" cellpadding="0">
288     <tr><td valign="top"></td><td valign="top"><em>handle</em>&nbsp;</td><td>handle to the kdb data structure </td></tr>
289     <tr><td valign="top"></td><td valign="top"><em>mountpoint</em>&nbsp;</td><td>the <a class="el" href="group__keyname.html#g8e805c726a60da921d3736cda7813513">keyName()</a> of this key is the mountpoint, <a class="el" href="group__keyvalue.html#g6f29609c5da53c6dc26a98678d5752af">keyValue()</a> the backend </td></tr>
290     <tr><td valign="top"></td><td valign="top"><em>config</em>&nbsp;</td><td>the configuration passed for that backend </td></tr>
291   </table>
292 </dl>
293 <dl class="return" compact><dt><b>Returns:</b></dt><dd>0 on success, -1 if an error occurred </dd></dl>
294
295 </div>
296 </div><p>
297 <a class="anchor" name="gb7be60c387892d2235907836c5060e1f"></a><!-- doxytag: member="kdb.c::kdbOpen" ref="gb7be60c387892d2235907836c5060e1f" args="()" -->
298 <div class="memitem">
299 <div class="memproto">
300       <table class="memname">
301         <tr>
302           <td class="memname">KDB* kdbOpen           </td>
303           <td>(</td>
304           <td class="paramtype">void&nbsp;</td>
305           <td class="paramname">          </td>
306           <td>&nbsp;)&nbsp;</td>
307           <td></td>
308         </tr>
309       </table>
310 </div>
311 <div class="memdoc">
312
313 <p>
314 Opens the session with the Key database.<p>
315 The first step is to open the default backend. With it system/elektra/mountpoints will be loaded and all needed libraries and mountpoints will be determined. These libraries for backends will be loaded and with it the <code>KDB</code> datastructure will be initialized.<p>
316 You must always call this method before retrieving or commiting any keys to the database. In the end of the program, after using the key database, you must not forget to <a class="el" href="group__kdb.html#gd9bb8bd3f1296bfa77cc9a1b41b7a859">kdbClose()</a>. You can use the atexit () handler for it.<p>
317 The pointer to the <code>KDB</code> structure returned will be initialized like described above, and it must be passed along on any kdb*() method your application calls.<p>
318 Get a <code>KDB</code> handle for every thread using elektra. Don't share the handle across threads, and also not the pointer accessing it: <div class="fragment"><pre class="fragment">thread1 {
319         KDB * h;
320         h = <a class="code" href="group__kdb.html#gb7be60c387892d2235907836c5060e1f">kdbOpen</a>();
321         <span class="comment">// fetch keys and work with them</span>
322         <a class="code" href="group__kdb.html#gd9bb8bd3f1296bfa77cc9a1b41b7a859">kdbClose</a>(h);
323 }
324 thread2 {
325         KDB * h;
326         h = <a class="code" href="group__kdb.html#gb7be60c387892d2235907836c5060e1f">kdbOpen</a>();
327         <span class="comment">// fetch keys and work with them</span>
328         <a class="code" href="group__kdb.html#gd9bb8bd3f1296bfa77cc9a1b41b7a859">kdbClose</a>(h);
329 }
330 </pre></div><p>
331 You don't need to use the <a class="el" href="group__kdb.html#gb7be60c387892d2235907836c5060e1f">kdbOpen()</a> if you only want to manipulate plain in-memory Key or KeySet objects without any affairs with the backend key database,<p>
332 <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__kdb.html#gd9bb8bd3f1296bfa77cc9a1b41b7a859">kdbClose()</a> to end all affairs to the <a class="el" href="group__key.html" title="Key construction and initialization methods.">Key :: Basic Methods</a> database. </dd></dl>
333 <dl class="return" compact><dt><b>Returns:</b></dt><dd>a KDB pointer on success <p>
334 NULL on failure </dd></dl>
335
336 </div>
337 </div><p>
338 <a class="anchor" name="g953cf29721e6000c2516cd6b5d36f571"></a><!-- doxytag: member="kdb.c::kdbSet" ref="g953cf29721e6000c2516cd6b5d36f571" args="(KDB *handle, KeySet *ks, Key *parentKey, option_t options)" -->
339 <div class="memitem">
340 <div class="memproto">
341       <table class="memname">
342         <tr>
343           <td class="memname">ssize_t kdbSet           </td>
344           <td>(</td>
345           <td class="paramtype">KDB *&nbsp;</td>
346           <td class="paramname"> <em>handle</em>, </td>
347         </tr>
348         <tr>
349           <td class="paramkey"></td>
350           <td></td>
351           <td class="paramtype">KeySet *&nbsp;</td>
352           <td class="paramname"> <em>ks</em>, </td>
353         </tr>
354         <tr>
355           <td class="paramkey"></td>
356           <td></td>
357           <td class="paramtype">Key *&nbsp;</td>
358           <td class="paramname"> <em>parentKey</em>, </td>
359         </tr>
360         <tr>
361           <td class="paramkey"></td>
362           <td></td>
363           <td class="paramtype">option_t&nbsp;</td>
364           <td class="paramname"> <em>options</em></td><td>&nbsp;</td>
365         </tr>
366         <tr>
367           <td></td>
368           <td>)</td>
369           <td></td><td></td><td></td>
370         </tr>
371       </table>
372 </div>
373 <div class="memdoc">
374
375 <p>
376 Set keys in an atomic and universal way, all other kdbSet Functions rely on that one.<p>
377 The given handle and keyset are the objects to work with.<p>
378 With parentKey you can only store a part of the given keyset. Otherwise pass a null pointer or a parentKey without a name.<p>
379 <div class="fragment"><pre class="fragment">KeySet *ks = <a class="code" href="group__keyset.html#g671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew</a>(0);
380 <a class="code" href="group__kdb.html#g37b44bda1b83bc0144916bf21a86c1b5">kdbGet</a> (h, ks, <a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"system/myapp"</span>,0), KDB_O_DEL);
381 <a class="code" href="group__kdb.html#g37b44bda1b83bc0144916bf21a86c1b5">kdbGet</a> (h, ks, <a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"user/myapp"</span>,0), KDB_O_DEL);
382
383 <span class="comment">//now only set everything below user, because you can't write to system</span>
384 <a class="code" href="group__kdb.html#g953cf29721e6000c2516cd6b5d36f571">kdbSet</a> (h, ks, <a class="code" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(<span class="stringliteral">"user/myapp"</span>,0), KDB_O_DEL);
385
386 <a class="code" href="group__keyset.html#g27e5c16473b02a422238c8d970db7ac8">ksDel</a> (ks);
387 </pre></div><p>
388 Each key is checked with <a class="el" href="group__keytest.html#gf247df0de7aca04b32ef80e39ef12950">keyNeedSync()</a> before being actually committed. So only changed keys are updated. If no key of a backend needs to be synced the <a class="el" href="group__backend.html#g2d86ff43b693d59d4b82b597756e9e23">kdbSet_backend()</a> will be omitted.<p>
389 If some error occurs, <a class="el" href="group__kdb.html#g953cf29721e6000c2516cd6b5d36f571">kdbSet()</a> will stop. In this situation the KeySet internal cursor will be set on the key that generated the error. This specific key and all behind it were not set. To be failsafe jump over it and try to set the rest, but report the error to the user.<p>
390 <dl class="user" compact><dt><b>Example of how this method can be used:</b></dt><dd><div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> i;
391 KeySet *ks;  <span class="comment">// the KeySet I want to set</span>
392 <span class="comment">// fill ks with some keys</span>
393 <span class="keywordflow">for</span> (i=0; i&lt; 10; i++) <span class="comment">// limit to 10 tries</span>
394 {
395         ret=<a class="code" href="group__kdb.html#g953cf29721e6000c2516cd6b5d36f571">kdbSet</a>(handle,ks, 0, 0);
396         <span class="keywordflow">if</span> (ret == -1)
397         {
398                 <span class="comment">// We got an error. Warn user.</span>
399                 Key *problem;
400                 problem=<a class="code" href="group__keyset.html#g4287b9416912c5f2ab9c195cb74fb094">ksCurrent</a>(ks);
401                 <span class="keywordflow">if</span> (problem)
402                 {
403                         <span class="keywordtype">char</span> keyname[300]=<span class="stringliteral">""</span>;
404                         <a class="code" href="group__keyname.html#gaba1494a5ffc976e0e56c43f4334a23c">keyGetFullName</a>(problem,keyname,<span class="keyword">sizeof</span>(keyname));
405                         fprintf(stderr,<span class="stringliteral">"kdb import: while importing %s"</span>, keyname);
406                 } <span class="keywordflow">else</span> <span class="keywordflow">break</span>;
407                 <span class="comment">// And try to set keys again starting from the next key,</span>
408                 <span class="comment">// unless we reached the end of KeySet</span>
409                 <span class="keywordflow">if</span> (<a class="code" href="group__keyset.html#g317321c9065b5a4b3e33fe1c399bcec9">ksNext</a>(ks) == 0) <span class="keywordflow">break</span>;
410         }
411 }
412 </pre></div></dd></dl>
413 <h2><a class="anchor" name="kdbsetoption">
414 Options</a></h2>
415 There are some options changing the behaviour of <a class="el" href="group__kdb.html#g953cf29721e6000c2516cd6b5d36f571">kdbSet()</a>:<p>
416 <ul>
417 <li><code>option_t::KDB_O_DEL</code> <br>
418  Its often useful to <a class="el" href="group__key.html#g3df95bbc2494e3e6703ece5639be5bb1">keyDel()</a> the parentKey in the line after <a class="el" href="group__kdb.html#g37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a>. Using this flag, you can just pass a key allocated with <a class="el" href="group__key.html#gf6893c038b3ebee90c73a9ea8356bebf">keyNew()</a>, <a class="el" href="group__kdb.html#g37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> will free it for you in the end.</li><li><code>option_t::KDB_O_SYNC</code> <br>
419  Will force to save all keys, independent of their sync state.</li><li><code>option_t::KDB_O_NOREMOVE</code> <br>
420  Don't remove any key from disk, even if <a class="el" href="group__keymeta.html#g6e14e5f1de26e1318100631a149f2984">keyRemove()</a> was set. With that flag removing keys can't happen unintentional. The flag will result in that all keys in <code>returned</code> don't have <a class="el" href="group__keytest.html#gae91159815480fbb3b3d9d7fa85e77b9">keyNeedRemove()</a> set.</li><li><code>option_t::KDB_O_REMOVEONLY</code> <br>
421  Remove all keys instead of setting them. All keys in <code>returned</code> will have <a class="el" href="group__keytest.html#gae91159815480fbb3b3d9d7fa85e77b9">keyNeedRemove()</a> set, but not <a class="el" href="group__keytest.html#g3908b6511648a950f37cd0005bfea5d5">keyNeedStat()</a> saying to you that the key was deleted permanently. This option implicit also activates <code>option_t::KDB_O_SYNC</code> because the sync state will be changed when they are marked remove. You might need option_t::KDB_O_INACTIVE set for the previous call of <a class="el" href="group__kdb.html#g37b44bda1b83bc0144916bf21a86c1b5">kdbGet()</a> if there are any. Otherwise the recursive remove will fail, because removing directories is only possible when all subkeys are removed.</li></ul>
422 <h2><a class="anchor" name="kdbsetdetail">
423 Details</a></h2>
424 When you dont have a parentKey or its name empty, then all keys will be set.<p>
425 You can remove some keys instead of setting them by marking them with <a class="el" href="group__keymeta.html#g6e14e5f1de26e1318100631a149f2984">keyRemove()</a>. The <a class="el" href="group__keytest.html#gf247df0de7aca04b32ef80e39ef12950">keyNeedSync()</a> flag will be unset after successful removing. But the <a class="el" href="group__keytest.html#gae91159815480fbb3b3d9d7fa85e77b9">keyNeedRemove()</a> flag will stay, but its safe to delete the key.<p>
426 <dl compact><dt><b>Parameters:</b></dt><dd>
427   <table border="0" cellspacing="2" cellpadding="0">
428     <tr><td valign="top"></td><td valign="top"><em>handle</em>&nbsp;</td><td>contains internal information of <a class="el" href="group__kdb.html#gb7be60c387892d2235907836c5060e1f">opened </a> key database </td></tr>
429     <tr><td valign="top"></td><td valign="top"><em>ks</em>&nbsp;</td><td>a KeySet which should contain changed keys, otherwise nothing is done </td></tr>
430     <tr><td valign="top"></td><td valign="top"><em>parentKey</em>&nbsp;</td><td>holds the information below which key keys should be set </td></tr>
431     <tr><td valign="top"></td><td valign="top"><em>options</em>&nbsp;</td><td>see in <a class="el" href="group__kdb.html#g953cf29721e6000c2516cd6b5d36f571">kdbSet()</a> documentation </td></tr>
432   </table>
433 </dl>
434 <dl class="return" compact><dt><b>Returns:</b></dt><dd>0 on success <p>
435 -1 on failure </dd></dl>
436 <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__keytest.html#gf247df0de7aca04b32ef80e39ef12950">keyNeedSync()</a>, <a class="el" href="group__keyset.html#g317321c9065b5a4b3e33fe1c399bcec9">ksNext()</a>, <a class="el" href="group__keyset.html#g4287b9416912c5f2ab9c195cb74fb094">ksCurrent()</a> <p>
437 <a class="el" href="group__keymeta.html#g6e14e5f1de26e1318100631a149f2984">keyRemove()</a>, <a class="el" href="group__keytest.html#gae91159815480fbb3b3d9d7fa85e77b9">keyNeedRemove()</a> <p>
438 commandEdit(), commandImport() code in <a class="el" href="group__kdb.html" title="General methods to access the Key database.">KDB :: Low Level Methods</a> command for usage and error handling example </dd></dl>
439
440 </div>
441 </div><p>
442 <a class="anchor" name="g400ca66a9bdc04ecadb66d84dc06bd55"></a><!-- doxytag: member="kdb.c::kdbUnmount" ref="g400ca66a9bdc04ecadb66d84dc06bd55" args="(KDB *handle, const Key *mountpoint)" -->
443 <div class="memitem">
444 <div class="memproto">
445       <table class="memname">
446         <tr>
447           <td class="memname">int kdbUnmount           </td>
448           <td>(</td>
449           <td class="paramtype">KDB *&nbsp;</td>
450           <td class="paramname"> <em>handle</em>, </td>
451         </tr>
452         <tr>
453           <td class="paramkey"></td>
454           <td></td>
455           <td class="paramtype">const Key *&nbsp;</td>
456           <td class="paramname"> <em>mountpoint</em></td><td>&nbsp;</td>
457         </tr>
458         <tr>
459           <td></td>
460           <td>)</td>
461           <td></td><td></td><td></td>
462         </tr>
463       </table>
464 </div>
465 <div class="memdoc">
466
467 <p>
468 Dynamically unmount a single backend.<p>
469 Unmount a backend that was mounted with <a class="el" href="group__kdb.html#g40e35f26cc69bd43ef1b2207f4fa121b">kdbMount()</a> before.<p>
470 <dl compact><dt><b>Parameters:</b></dt><dd>
471   <table border="0" cellspacing="2" cellpadding="0">
472     <tr><td valign="top"></td><td valign="top"><em>handle</em>&nbsp;</td><td>handle to the kdb data structure </td></tr>
473     <tr><td valign="top"></td><td valign="top"><em>mountpoint</em>&nbsp;</td><td>directory where backend is mounted to, that should be unmounted </td></tr>
474   </table>
475 </dl>
476 <dl class="return" compact><dt><b>Returns:</b></dt><dd>0 on success, -1 if an error ocurred. </dd></dl>
477
478 </div>
479 </div><p>
480 </div>
481 <hr size="1"><address style="text-align: right;"><small>Generated on Tue Jun 30 14:43:54 2009 for Elektra Projekt by&nbsp;
482 <a href="http://www.doxygen.org/index.html">
483 <img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.6 </small></address>
484 </body>
485 </html>