doc/elektra-api/html/group__backendhelper.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 Backends :: Backend Helper for Elektra</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 Backends :: Backend Helper for Elektra</h1>Backend helper Methods for Elektra and Backends.
  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__backendhelper.html#gcea5819334a71744a54a6b290a8c3bdc">kdbbWriteLock</a> (FILE *f)</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__backendhelper.html#g89aa8c310a5720766639c305e643c069">kdbbReadLock</a> (FILE *f)</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__backendhelper.html#gb969d5d25762464c5f719f4f90757fe8">kdbbUnlock</a> (FILE *f)</td></tr>
  27
  28 <tr><td class="memItemLeft" nowrap align="right" valign="top">ssize_t&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#gba58d73495f15a309468fd4798539f22">kdbbEncode</a> (void *kdbbDecoded, size_t size, char *returned)</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__backendhelper.html#gfc099de90661f22a048d5fd16fca48f5">kdbbDecode</a> (char *kdbbEncoded, void *returned)</td></tr>
  31
  32 <tr><td class="memItemLeft" nowrap align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#g11b83ea1eac5adb730c3f51660cded9d">kdbbNeedsUTF8Conversion</a> ()</td></tr>
  33
  34 <tr><td class="memItemLeft" nowrap align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#g5b9a2cb642f2a626037c4c730c790c65">kdbbUTF8Engine</a> (int direction, char **string, size_t *inputOutputByteSize)</td></tr>
  35
  36 <tr><td class="memItemLeft" nowrap align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#gac1bda629cb9912eaaaa785b2874cad1">kdbbEncodeChar</a> (char c, char *buffer, size_t bufSize)</td></tr>
  37
  38 <tr><td class="memItemLeft" nowrap align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#g0ae368114cb42f6f6d56bc5cc96e44cf">kdbbDecodeChar</a> (const char *from, char *into)</td></tr>
  39
  40 <tr><td class="memItemLeft" nowrap align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#ge3ac53e11feb9d7ff956a4562f1d9bde">kdbbFilenameToKeyName</a> (const char *string, char *buffer, int bufSize)</td></tr>
  41
  42 <tr><td class="memItemLeft" nowrap align="right" valign="top">ssize_t&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#g10364b65d79e44f99f9464e50dffa900">kdbbGetFullKeyName</a> (KDB *handle, const char *forFilename, const Key *parentKey, Key *returned)</td></tr>
  43
  44 <tr><td class="memItemLeft" nowrap align="right" valign="top">int&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#g93921f5f2169e9d6ba1603807ee5bc2d">kdbbKeyNameToRelativeFilename</a> (const char *string, char *buffer, size_t bufSize)</td></tr>
  45
  46 <tr><td class="memItemLeft" nowrap align="right" valign="top">ssize_t&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#g1d09dab69a7d6cee9a1eb2c1c650051e">kdbbKeyCalcRelativeFilename</a> (const Key *key, char *relativeFilename, size_t maxSize)</td></tr>
  47
  48 <tr><td class="memItemLeft" nowrap align="right" valign="top">ssize_t&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#g6db2e7738f905ea0ab52b5c9c3981af6">kdbbGetFullFilename</a> (KDB *handle, const Key *forKey, char *returned, size_t maxSize)</td></tr>
  49
  50 </table>
  51 <hr><a name="_details"></a><h2>Detailed Description</h2>
  52 Backend helper Methods for Elektra and Backends.
  53 <p>
  54 To use them: <div class="fragment"><pre class="fragment"><span class="preprocessor"> #include &lt;kdbbackend.h&gt;</span>
  55 </pre></div><p>
  56 These backend helper methods provide functionality commonly used by backends to make backend development easier and to provide the same behaviour between backends. <hr><h2>Function Documentation</h2>
  57 <a class="anchor" name="gfc099de90661f22a048d5fd16fca48f5"></a><!-- doxytag: member="helper.c::kdbbDecode" ref="gfc099de90661f22a048d5fd16fca48f5" args="(char *kdbbEncoded, void *returned)" -->
  58 <div class="memitem">
  59 <div class="memproto">
  60       <table class="memname">
  61         <tr>
  62           <td class="memname">ssize_t kdbbDecode           </td>
  63           <td>(</td>
  64           <td class="paramtype">char *&nbsp;</td>
  65           <td class="paramname"> <em>kdbbEncoded</em>, </td>
  66         </tr>
  67         <tr>
  68           <td class="paramkey"></td>
  69           <td></td>
  70           <td class="paramtype">void *&nbsp;</td>
  71           <td class="paramname"> <em>returned</em></td><td>&nbsp;</td>
  72         </tr>
  73         <tr>
  74           <td></td>
  75           <td>)</td>
  76           <td></td><td></td><td></td>
  77         </tr>
  78       </table>
  79 </div>
  80 <div class="memdoc">
  81
  82 <p>
  83 UnkdbbEncodes a buffer of ASCII hexadecimal values into a byte stream.<p>
  84 The allowed format for the hexadecimal values is just a stream of pairs of plain hex-digits, all together or space-separated.<p>
  85 The <code>returned</code> data won't be bigger than half the size of the source <code>kdbbEncoded</code> data.<p>
  86 <dl compact><dt><b>Parameters:</b></dt><dd>
  87   <table border="0" cellspacing="2" cellpadding="0">
  88     <tr><td valign="top"></td><td valign="top"><em>kdbbEncoded</em>&nbsp;</td><td>the source of ASCII hexadecimal digits. </td></tr>
  89     <tr><td valign="top"></td><td valign="top"><em>returned</em>&nbsp;</td><td>preallocated destination for the kdbbDecoded data. </td></tr>
  90   </table>
  91 </dl>
  92 <dl class="return" compact><dt><b>Returns:</b></dt><dd>the amount of bytes kdbbDecoded <p>
  93 -1 on failure </dd></dl>
  94 <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__backendhelper.html#gba58d73495f15a309468fd4798539f22">kdbbEncode()</a> </dd></dl>
  95
  96 </div>
  97 </div><p>
  98 <a class="anchor" name="g0ae368114cb42f6f6d56bc5cc96e44cf"></a><!-- doxytag: member="helper.c::kdbbDecodeChar" ref="g0ae368114cb42f6f6d56bc5cc96e44cf" args="(const char *from, char *into)" -->
  99 <div class="memitem">
 100 <div class="memproto">
 101       <table class="memname">
 102         <tr>
 103           <td class="memname">int kdbbDecodeChar           </td>
 104           <td>(</td>
 105           <td class="paramtype">const char *&nbsp;</td>
 106           <td class="paramname"> <em>from</em>, </td>
 107         </tr>
 108         <tr>
 109           <td class="paramkey"></td>
 110           <td></td>
 111           <td class="paramtype">char *&nbsp;</td>
 112           <td class="paramname"> <em>into</em></td><td>&nbsp;</td>
 113         </tr>
 114         <tr>
 115           <td></td>
 116           <td>)</td>
 117           <td></td><td></td><td></td>
 118         </tr>
 119       </table>
 120 </div>
 121 <div class="memdoc">
 122
 123 <p>
 124 Char decoding.<p>
 125 Decode one char from 25, 2B, 2F, 2C following RFC 2396 or copy char untouched if different.<p>
 126 <dl compact><dt><b>Parameters:</b></dt><dd>
 127   <table border="0" cellspacing="2" cellpadding="0">
 128     <tr><td valign="top"></td><td valign="top"><em>from</em>&nbsp;</td><td>String containing sequence to decode </td></tr>
 129     <tr><td valign="top"></td><td valign="top"><em>into</em>&nbsp;</td><td>Decoded char </td></tr>
 130   </table>
 131 </dl>
 132 <dl class="return" compact><dt><b>Returns:</b></dt><dd>: Positive size of byte read from "from" for decoding the sequence if sucess or -1 if error (into untouched)</dd></dl>
 133 <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__backendhelper.html#gac1bda629cb9912eaaaa785b2874cad1">kdbbEncodeChar</a></dd></dl>
 134 NOTE: No '\0' is added at the end of buffer.
 135 </div>
 136 </div><p>
 137 <a class="anchor" name="gba58d73495f15a309468fd4798539f22"></a><!-- doxytag: member="helper.c::kdbbEncode" ref="gba58d73495f15a309468fd4798539f22" args="(void *kdbbDecoded, size_t size, char *returned)" -->
 138 <div class="memitem">
 139 <div class="memproto">
 140       <table class="memname">
 141         <tr>
 142           <td class="memname">ssize_t kdbbEncode           </td>
 143           <td>(</td>
 144           <td class="paramtype">void *&nbsp;</td>
 145           <td class="paramname"> <em>kdbbDecoded</em>, </td>
 146         </tr>
 147         <tr>
 148           <td class="paramkey"></td>
 149           <td></td>
 150           <td class="paramtype">size_t&nbsp;</td>
 151           <td class="paramname"> <em>size</em>, </td>
 152         </tr>
 153         <tr>
 154           <td class="paramkey"></td>
 155           <td></td>
 156           <td class="paramtype">char *&nbsp;</td>
 157           <td class="paramname"> <em>returned</em></td><td>&nbsp;</td>
 158         </tr>
 159         <tr>
 160           <td></td>
 161           <td>)</td>
 162           <td></td><td></td><td></td>
 163         </tr>
 164       </table>
 165 </div>
 166 <div class="memdoc">
 167
 168 <p>
 169 Encodes a buffer of data onto hexadecimal ASCII.<p>
 170 The resulting data is made up of pairs of ASCII hex-digits, space- and newline-separated. This is the counterpart of <a class="el" href="group__backendhelper.html#gfc099de90661f22a048d5fd16fca48f5">kdbbDecode()</a>.<p>
 171 The <code>returned</code> must allocated prior you call this function and won't be bigger than 3 times the size of the source <code>kdbbDecoded</code> + 1 byte.<p>
 172 <dl compact><dt><b>Parameters:</b></dt><dd>
 173   <table border="0" cellspacing="2" cellpadding="0">
 174     <tr><td valign="top"></td><td valign="top"><em>kdbbDecoded</em>&nbsp;</td><td>the source buffer. </td></tr>
 175     <tr><td valign="top"></td><td valign="top"><em>size</em>&nbsp;</td><td>the size of the source buffer in bytes. </td></tr>
 176     <tr><td valign="top"></td><td valign="top"><em>returned</em>&nbsp;</td><td>the preallocated destination for the ASCII-kdbbEncoded data. </td></tr>
 177   </table>
 178 </dl>
 179 <dl class="return" compact><dt><b>Returns:</b></dt><dd>the amount of bytes used in the resulting kdbbEncoded buffer. </dd></dl>
 180 <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__backendhelper.html#gfc099de90661f22a048d5fd16fca48f5">kdbbDecode()</a> </dd></dl>
 181
 182 </div>
 183 </div><p>
 184 <a class="anchor" name="gac1bda629cb9912eaaaa785b2874cad1"></a><!-- doxytag: member="helper.c::kdbbEncodeChar" ref="gac1bda629cb9912eaaaa785b2874cad1" args="(char c, char *buffer, size_t bufSize)" -->
 185 <div class="memitem">
 186 <div class="memproto">
 187       <table class="memname">
 188         <tr>
 189           <td class="memname">int kdbbEncodeChar           </td>
 190           <td>(</td>
 191           <td class="paramtype">char&nbsp;</td>
 192           <td class="paramname"> <em>c</em>, </td>
 193         </tr>
 194         <tr>
 195           <td class="paramkey"></td>
 196           <td></td>
 197           <td class="paramtype">char *&nbsp;</td>
 198           <td class="paramname"> <em>buffer</em>, </td>
 199         </tr>
 200         <tr>
 201           <td class="paramkey"></td>
 202           <td></td>
 203           <td class="paramtype">size_t&nbsp;</td>
 204           <td class="paramname"> <em>bufSize</em></td><td>&nbsp;</td>
 205         </tr>
 206         <tr>
 207           <td></td>
 208           <td>)</td>
 209           <td></td><td></td><td></td>
 210         </tr>
 211       </table>
 212 </div>
 213 <div class="memdoc">
 214
 215 <p>
 216 Char encoding.<p>
 217 Encode '/', '\', '', '+', ' ' char following RFC 2396 or copy char untouched if different.<p>
 218 <dl compact><dt><b>Parameters:</b></dt><dd>
 219   <table border="0" cellspacing="2" cellpadding="0">
 220     <tr><td valign="top"></td><td valign="top"><em>c</em>&nbsp;</td><td>Char to kdbbEncode </td></tr>
 221     <tr><td valign="top"></td><td valign="top"><em>buffer</em>&nbsp;</td><td>string wich will contain kdbbEncoded char </td></tr>
 222     <tr><td valign="top"></td><td valign="top"><em>bufSize</em>&nbsp;</td><td>Size of the buffer </td></tr>
 223   </table>
 224 </dl>
 225 <dl class="return" compact><dt><b>Returns:</b></dt><dd>: Size of the kdbbEncoded string if success or -1 if error * (then buffer is untouched)</dd></dl>
 226 <dl class="see" compact><dt><b>See also:</b></dt><dd>kdbiDecodeChar</dd></dl>
 227 NOTE: No '\0' is added at the end of buffer.
 228 </div>
 229 </div><p>
 230 <a class="anchor" name="ge3ac53e11feb9d7ff956a4562f1d9bde"></a><!-- doxytag: member="helper.c::kdbbFilenameToKeyName" ref="ge3ac53e11feb9d7ff956a4562f1d9bde" args="(const char *string, char *buffer, int bufSize)" -->
 231 <div class="memitem">
 232 <div class="memproto">
 233       <table class="memname">
 234         <tr>
 235           <td class="memname">int kdbbFilenameToKeyName           </td>
 236           <td>(</td>
 237           <td class="paramtype">const char *&nbsp;</td>
 238           <td class="paramname"> <em>string</em>, </td>
 239         </tr>
 240         <tr>
 241           <td class="paramkey"></td>
 242           <td></td>
 243           <td class="paramtype">char *&nbsp;</td>
 244           <td class="paramname"> <em>buffer</em>, </td>
 245         </tr>
 246         <tr>
 247           <td class="paramkey"></td>
 248           <td></td>
 249           <td class="paramtype">int&nbsp;</td>
 250           <td class="paramname"> <em>bufSize</em></td><td>&nbsp;</td>
 251         </tr>
 252         <tr>
 253           <td></td>
 254           <td>)</td>
 255           <td></td><td></td><td></td>
 256         </tr>
 257       </table>
 258 </div>
 259 <div class="memdoc">
 260
 261 <p>
 262 Translate a relative file name to a key name applying decoding.<p>
 263 <dl compact><dt><b>Parameters:</b></dt><dd>
 264   <table border="0" cellspacing="2" cellpadding="0">
 265     <tr><td valign="top"></td><td valign="top"><em>string</em>&nbsp;</td><td>Filename </td></tr>
 266     <tr><td valign="top"></td><td valign="top"><em>buffer</em>&nbsp;</td><td>decoded keyName </td></tr>
 267     <tr><td valign="top"></td><td valign="top"><em>bufSize</em>&nbsp;</td><td>Size of buffer </td></tr>
 268   </table>
 269 </dl>
 270 <dl class="return" compact><dt><b>Returns:</b></dt><dd>0 on success <p>
 271 -1 on failure</dd></dl>
 272 <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__backendhelper.html#g93921f5f2169e9d6ba1603807ee5bc2d">kdbbKeyNameToRelativeFilename</a> </dd></dl>
 273
 274 </div>
 275 </div><p>
 276 <a class="anchor" name="g6db2e7738f905ea0ab52b5c9c3981af6"></a><!-- doxytag: member="helper.c::kdbbGetFullFilename" ref="g6db2e7738f905ea0ab52b5c9c3981af6" args="(KDB *handle, const Key *forKey, char *returned, size_t maxSize)" -->
 277 <div class="memitem">
 278 <div class="memproto">
 279       <table class="memname">
 280         <tr>
 281           <td class="memname">ssize_t kdbbGetFullFilename           </td>
 282           <td>(</td>
 283           <td class="paramtype">KDB *&nbsp;</td>
 284           <td class="paramname"> <em>handle</em>, </td>
 285         </tr>
 286         <tr>
 287           <td class="paramkey"></td>
 288           <td></td>
 289           <td class="paramtype">const Key *&nbsp;</td>
 290           <td class="paramname"> <em>forKey</em>, </td>
 291         </tr>
 292         <tr>
 293           <td class="paramkey"></td>
 294           <td></td>
 295           <td class="paramtype">char *&nbsp;</td>
 296           <td class="paramname"> <em>returned</em>, </td>
 297         </tr>
 298         <tr>
 299           <td class="paramkey"></td>
 300           <td></td>
 301           <td class="paramtype">size_t&nbsp;</td>
 302           <td class="paramname"> <em>maxSize</em></td><td>&nbsp;</td>
 303         </tr>
 304         <tr>
 305           <td></td>
 306           <td>)</td>
 307           <td></td><td></td><td></td>
 308         </tr>
 309       </table>
 310 </div>
 311 <div class="memdoc">
 312
 313 <p>
 314 Calculate the real file name for a key.<p>
 315 system/ keys will get the prefix KDB_DB_SYSTEM<p>
 316 For the user/ keys the algorithm works as follow: 1.) When the override environment KDB_HOME exists the configuration will be searched below KDB_HOME/KDB_DB_USER 2.) When the owner of the key exists in the elektra user database steps a.) and b.) will be tested: a.) The specific value for configuration storage of the user below system/users/&lt;owner&gt;/kdb b.) The home variable in system/users/&lt;owner&gt;/home will be merged together with KDB_DB_USER 3.) When the environment HOME exists the configuration will be searched below HOME/KDB_DB_USER 4.) Otherwise the KDB_DB_HOME/&lt;owner&gt;/KDB_DB_USER will be used<p>
 317 <dl compact><dt><b>Parameters:</b></dt><dd>
 318   <table border="0" cellspacing="2" cellpadding="0">
 319     <tr><td valign="top"></td><td valign="top"><em>forKey</em>&nbsp;</td><td>the key object to work with </td></tr>
 320     <tr><td valign="top"></td><td valign="top"><em>handle</em>&nbsp;</td><td>the kdb handle to work with </td></tr>
 321     <tr><td valign="top"></td><td valign="top"><em>returned</em>&nbsp;</td><td>the buffer to return the calculated filename </td></tr>
 322     <tr><td valign="top"></td><td valign="top"><em>maxSize</em>&nbsp;</td><td>maximum number of bytes that fit the buffer </td></tr>
 323   </table>
 324 </dl>
 325 <dl class="see" compact><dt><b>See also:</b></dt><dd>kdbCalcRelativeFilename() </dd></dl>
 326 <dl class="return" compact><dt><b>Returns:</b></dt><dd>number of bytes written to the buffer, or 0 on error<p>
 327 length of returned string on success <p>
 328 -1 on failure </dd></dl>
 329
 330 </div>
 331 </div><p>
 332 <a class="anchor" name="g10364b65d79e44f99f9464e50dffa900"></a><!-- doxytag: member="helper.c::kdbbGetFullKeyName" ref="g10364b65d79e44f99f9464e50dffa900" args="(KDB *handle, const char *forFilename, const Key *parentKey, Key *returned)" -->
 333 <div class="memitem">
 334 <div class="memproto">
 335       <table class="memname">
 336         <tr>
 337           <td class="memname">ssize_t kdbbGetFullKeyName           </td>
 338           <td>(</td>
 339           <td class="paramtype">KDB *&nbsp;</td>
 340           <td class="paramname"> <em>handle</em>, </td>
 341         </tr>
 342         <tr>
 343           <td class="paramkey"></td>
 344           <td></td>
 345           <td class="paramtype">const char *&nbsp;</td>
 346           <td class="paramname"> <em>forFilename</em>, </td>
 347         </tr>
 348         <tr>
 349           <td class="paramkey"></td>
 350           <td></td>
 351           <td class="paramtype">const Key *&nbsp;</td>
 352           <td class="paramname"> <em>parentKey</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>returned</em></td><td>&nbsp;</td>
 359         </tr>
 360         <tr>
 361           <td></td>
 362           <td>)</td>
 363           <td></td><td></td><td></td>
 364         </tr>
 365       </table>
 366 </div>
 367 <div class="memdoc">
 368
 369 <p>
 370 Calculates the keyname out of a relative filename.<p>
 371 <dl compact><dt><b>Parameters:</b></dt><dd>
 372   <table border="0" cellspacing="2" cellpadding="0">
 373     <tr><td valign="top"></td><td valign="top"><em>handle</em>&nbsp;</td><td>The kdb handle to work with </td></tr>
 374     <tr><td valign="top"></td><td valign="top"><em>forFilename</em>&nbsp;</td><td>needs to be the a null terminated string containing the relative filename </td></tr>
 375     <tr><td valign="top"></td><td valign="top"><em>parentKey</em>&nbsp;</td><td>is the key above the key which will be returned </td></tr>
 376     <tr><td valign="top"></td><td valign="top"><em>returned</em>&nbsp;</td><td>The proper keyname and owner will be stored in returned. A valid key must be passed. </td></tr>
 377   </table>
 378 </dl>
 379 <dl class="return" compact><dt><b>Returns:</b></dt><dd>number of bytes written to the buffer, or 0 on error<p>
 380 length of returned string on success <p>
 381 -1 on failure </dd></dl>
 382 <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__backendhelper.html#g93921f5f2169e9d6ba1603807ee5bc2d">kdbbKeyNameToRelativeFilename()</a> </dd></dl>
 383
 384 </div>
 385 </div><p>
 386 <a class="anchor" name="g1d09dab69a7d6cee9a1eb2c1c650051e"></a><!-- doxytag: member="helper.c::kdbbKeyCalcRelativeFilename" ref="g1d09dab69a7d6cee9a1eb2c1c650051e" args="(const Key *key, char *relativeFilename, size_t maxSize)" -->
 387 <div class="memitem">
 388 <div class="memproto">
 389       <table class="memname">
 390         <tr>
 391           <td class="memname">ssize_t kdbbKeyCalcRelativeFilename           </td>
 392           <td>(</td>
 393           <td class="paramtype">const Key *&nbsp;</td>
 394           <td class="paramname"> <em>key</em>, </td>
 395         </tr>
 396         <tr>
 397           <td class="paramkey"></td>
 398           <td></td>
 399           <td class="paramtype">char *&nbsp;</td>
 400           <td class="paramname"> <em>relativeFilename</em>, </td>
 401         </tr>
 402         <tr>
 403           <td class="paramkey"></td>
 404           <td></td>
 405           <td class="paramtype">size_t&nbsp;</td>
 406           <td class="paramname"> <em>maxSize</em></td><td>&nbsp;</td>
 407         </tr>
 408         <tr>
 409           <td></td>
 410           <td>)</td>
 411           <td></td><td></td><td></td>
 412         </tr>
 413       </table>
 414 </div>
 415 <div class="memdoc">
 416
 417 <p>
 418 This is a helper to kdbGetFullFilename()<p>
 419 <dl compact><dt><b>Parameters:</b></dt><dd>
 420   <table border="0" cellspacing="2" cellpadding="0">
 421     <tr><td valign="top"></td><td valign="top"><em>key</em>&nbsp;</td><td>has the relevant name for the relative filename </td></tr>
 422     <tr><td valign="top"></td><td valign="top"><em>relativeFilename</em>&nbsp;</td><td>the buffer to return the calculated filename </td></tr>
 423     <tr><td valign="top"></td><td valign="top"><em>maxSize</em>&nbsp;</td><td>maximum number of bytes that fit the buffer </td></tr>
 424   </table>
 425 </dl>
 426 <dl class="see" compact><dt><b>See also:</b></dt><dd>kdbGetFullFilename() </dd></dl>
 427 <dl class="return" compact><dt><b>Returns:</b></dt><dd>number of bytes written to the buffer <p>
 428 -1 on failure </dd></dl>
 429
 430 </div>
 431 </div><p>
 432 <a class="anchor" name="g93921f5f2169e9d6ba1603807ee5bc2d"></a><!-- doxytag: member="helper.c::kdbbKeyNameToRelativeFilename" ref="g93921f5f2169e9d6ba1603807ee5bc2d" args="(const char *string, char *buffer, size_t bufSize)" -->
 433 <div class="memitem">
 434 <div class="memproto">
 435       <table class="memname">
 436         <tr>
 437           <td class="memname">int kdbbKeyNameToRelativeFilename           </td>
 438           <td>(</td>
 439           <td class="paramtype">const char *&nbsp;</td>
 440           <td class="paramname"> <em>string</em>, </td>
 441         </tr>
 442         <tr>
 443           <td class="paramkey"></td>
 444           <td></td>
 445           <td class="paramtype">char *&nbsp;</td>
 446           <td class="paramname"> <em>buffer</em>, </td>
 447         </tr>
 448         <tr>
 449           <td class="paramkey"></td>
 450           <td></td>
 451           <td class="paramtype">size_t&nbsp;</td>
 452           <td class="paramname"> <em>bufSize</em></td><td>&nbsp;</td>
 453         </tr>
 454         <tr>
 455           <td></td>
 456           <td>)</td>
 457           <td></td><td></td><td></td>
 458         </tr>
 459       </table>
 460 </div>
 461 <div class="memdoc">
 462
 463 <p>
 464 Translate a key name to a relative file name applying encoding.<p>
 465 <dl compact><dt><b>Parameters:</b></dt><dd>
 466   <table border="0" cellspacing="2" cellpadding="0">
 467     <tr><td valign="top"></td><td valign="top"><em>string</em>&nbsp;</td><td>Keyname </td></tr>
 468     <tr><td valign="top"></td><td valign="top"><em>buffer</em>&nbsp;</td><td>kdbbEncoded filename </td></tr>
 469     <tr><td valign="top"></td><td valign="top"><em>bufSize</em>&nbsp;</td><td>Size of buffer </td></tr>
 470   </table>
 471 </dl>
 472 <dl class="return" compact><dt><b>Returns:</b></dt><dd>Number of byte written in buffer on success, <p>
 473 -1 on failure</dd></dl>
 474 <dl class="see" compact><dt><b>See also:</b></dt><dd><a class="el" href="group__backendhelper.html#g93921f5f2169e9d6ba1603807ee5bc2d">kdbbKeyNameToRelativeFilename</a> </dd></dl>
 475
 476 </div>
 477 </div><p>
 478 <a class="anchor" name="g11b83ea1eac5adb730c3f51660cded9d"></a><!-- doxytag: member="helper.c::kdbbNeedsUTF8Conversion" ref="g11b83ea1eac5adb730c3f51660cded9d" args="()" -->
 479 <div class="memitem">
 480 <div class="memproto">
 481       <table class="memname">
 482         <tr>
 483           <td class="memname">int kdbbNeedsUTF8Conversion           </td>
 484           <td>(</td>
 485           <td class="paramtype">void&nbsp;</td>
 486           <td class="paramname">          </td>
 487           <td>&nbsp;)&nbsp;</td>
 488           <td></td>
 489         </tr>
 490       </table>
 491 </div>
 492 <div class="memdoc">
 493
 494 <p>
 495 Checks if UTF-8 conversion is needed in current context. if nl_langinfo() is not available, no conversion is ever needed. If iconv usage is disabled there is no need to check if we need to convert. Furthermore, some systems have nl_langinfo(), but lacks ability to get CODESET through it. Look at the comments by the <a class="el" href="group__backendhelper.html#g5b9a2cb642f2a626037c4c730c790c65">kdbbUTF8Engine()</a> function for more information.<p>
 496 <dl class="return" compact><dt><b>Returns:</b></dt><dd>0 if not needed <p>
 497 anything else if needed </dd></dl>
 498
 499 </div>
 500 </div><p>
 501 <a class="anchor" name="g89aa8c310a5720766639c305e643c069"></a><!-- doxytag: member="helper.c::kdbbReadLock" ref="g89aa8c310a5720766639c305e643c069" args="(FILE *f)" -->
 502 <div class="memitem">
 503 <div class="memproto">
 504       <table class="memname">
 505         <tr>
 506           <td class="memname">int kdbbReadLock           </td>
 507           <td>(</td>
 508           <td class="paramtype">FILE *&nbsp;</td>
 509           <td class="paramname"> <em>f</em>          </td>
 510           <td>&nbsp;)&nbsp;</td>
 511           <td></td>
 512         </tr>
 513       </table>
 514 </div>
 515 <div class="memdoc">
 516
 517 <p>
 518 Locks file for read mode.<p>
 519 Other processes and threads are allowed to read the file too simultaneous.<p>
 520 <dl compact><dt><b>Parameters:</b></dt><dd>
 521   <table border="0" cellspacing="2" cellpadding="0">
 522     <tr><td valign="top"></td><td valign="top"><em>f</em>&nbsp;</td><td>is a valid filedescriptor </td></tr>
 523   </table>
 524 </dl>
 525 <dl class="return" compact><dt><b>Returns:</b></dt><dd>0 on success <p>
 526 -1 on failure</dd></dl>
 527 <dl compact><dt><b><a class="el" href="err.html#_err000002">Error:</a></b></dt><dd>sets KDB_ERR_NOLOCK when locking failed </dd></dl>
 528
 529 </div>
 530 </div><p>
 531 <a class="anchor" name="gb969d5d25762464c5f719f4f90757fe8"></a><!-- doxytag: member="helper.c::kdbbUnlock" ref="gb969d5d25762464c5f719f4f90757fe8" args="(FILE *f)" -->
 532 <div class="memitem">
 533 <div class="memproto">
 534       <table class="memname">
 535         <tr>
 536           <td class="memname">int kdbbUnlock           </td>
 537           <td>(</td>
 538           <td class="paramtype">FILE *&nbsp;</td>
 539           <td class="paramname"> <em>f</em>          </td>
 540           <td>&nbsp;)&nbsp;</td>
 541           <td></td>
 542         </tr>
 543       </table>
 544 </div>
 545 <div class="memdoc">
 546
 547 <p>
 548 Unlocks file.<p>
 549 <dl compact><dt><b>Parameters:</b></dt><dd>
 550   <table border="0" cellspacing="2" cellpadding="0">
 551     <tr><td valign="top"></td><td valign="top"><em>f</em>&nbsp;</td><td>is a valid filedescriptor </td></tr>
 552   </table>
 553 </dl>
 554 <dl class="return" compact><dt><b>Returns:</b></dt><dd>0 on success <p>
 555 -1 on failure</dd></dl>
 556 <dl compact><dt><b><a class="el" href="err.html#_err000003">Error:</a></b></dt><dd>sets KDB_ERR_NOLOCK when locking failed </dd></dl>
 557
 558 </div>
 559 </div><p>
 560 <a class="anchor" name="g5b9a2cb642f2a626037c4c730c790c65"></a><!-- doxytag: member="helper.c::kdbbUTF8Engine" ref="g5b9a2cb642f2a626037c4c730c790c65" args="(int direction, char **string, size_t *inputOutputByteSize)" -->
 561 <div class="memitem">
 562 <div class="memproto">
 563       <table class="memname">
 564         <tr>
 565           <td class="memname">int kdbbUTF8Engine           </td>
 566           <td>(</td>
 567           <td class="paramtype">int&nbsp;</td>
 568           <td class="paramname"> <em>direction</em>, </td>
 569         </tr>
 570         <tr>
 571           <td class="paramkey"></td>
 572           <td></td>
 573           <td class="paramtype">char **&nbsp;</td>
 574           <td class="paramname"> <em>string</em>, </td>
 575         </tr>
 576         <tr>
 577           <td class="paramkey"></td>
 578           <td></td>
 579           <td class="paramtype">size_t *&nbsp;</td>
 580           <td class="paramname"> <em>inputOutputByteSize</em></td><td>&nbsp;</td>
 581         </tr>
 582         <tr>
 583           <td></td>
 584           <td>)</td>
 585           <td></td><td></td><td></td>
 586         </tr>
 587       </table>
 588 </div>
 589 <div class="memdoc">
 590
 591 <p>
 592 Converts string to (<code>direction</code> = <code>UTF8_TO</code>) and from (<code>direction</code> = <code>UTF8_FROM</code>) UTF-8.<p>
 593 Since Elektra provides portability for key names and string values between different codesets, you should use this helper in your backend to convert to and from universal UTF-8 strings, when storing key names, values and comments.<p>
 594 Broken locales in applications can cause problems too. Make sure to load the environment locales in your application using <div class="fragment"><pre class="fragment">setlocale (LC_ALL, <span class="stringliteral">""</span>);
 595 </pre></div><p>
 596 Otherwise kdbbUTF8Engine will quit with -1 leading that backends return with error when non-ascii characters appear. Binary values are not effected.<p>
 597 If iconv() or nl_langinfo() is not available on your system, or if iconv() usage is disabled (--disable-iconv on build time) simply return 0 immediately.<p>
 598 <dl compact><dt><b>Parameters:</b></dt><dd>
 599   <table border="0" cellspacing="2" cellpadding="0">
 600     <tr><td valign="top"></td><td valign="top"><em>direction</em>&nbsp;</td><td>must be <code>UTF8_TO</code> (convert from current non-UTF-8 to UTF-8) or <code>UTF8_FROM</code> (convert from UTF-8 to current non-UTF-8) </td></tr>
 601     <tr><td valign="top"></td><td valign="top"><em>string</em>&nbsp;</td><td>before the call: the string to be converted; after the call: reallocated to carry the converted string </td></tr>
 602     <tr><td valign="top"></td><td valign="top"><em>inputOutputByteSize</em>&nbsp;</td><td>before the call: the size of the string including leading NULL; after the call: the size of the converted string including leading NULL </td></tr>
 603   </table>
 604 </dl>
 605 <dl class="return" compact><dt><b>Returns:</b></dt><dd>0 on success <p>
 606 -1 on failure </dd></dl>
 607
 608 </div>
 609 </div><p>
 610 <a class="anchor" name="gcea5819334a71744a54a6b290a8c3bdc"></a><!-- doxytag: member="helper.c::kdbbWriteLock" ref="gcea5819334a71744a54a6b290a8c3bdc" args="(FILE *f)" -->
 611 <div class="memitem">
 612 <div class="memproto">
 613       <table class="memname">
 614         <tr>
 615           <td class="memname">int kdbbWriteLock           </td>
 616           <td>(</td>
 617           <td class="paramtype">FILE *&nbsp;</td>
 618           <td class="paramname"> <em>f</em>          </td>
 619           <td>&nbsp;)&nbsp;</td>
 620           <td></td>
 621         </tr>
 622       </table>
 623 </div>
 624 <div class="memdoc">
 625
 626 <p>
 627 Locks file for exclusive write mode.<p>
 628 This function will block until all reader and writer have left the file.<p>
 629 <dl compact><dt><b>Parameters:</b></dt><dd>
 630   <table border="0" cellspacing="2" cellpadding="0">
 631     <tr><td valign="top"></td><td valign="top"><em>f</em>&nbsp;</td><td>is a valid filedescriptor </td></tr>
 632   </table>
 633 </dl>
 634 <dl class="return" compact><dt><b>Returns:</b></dt><dd>0 on success <p>
 635 -1 on failure</dd></dl>
 636 <dl compact><dt><b><a class="el" href="err.html#_err000001">Error:</a></b></dt><dd>sets KDB_ERR_NOLOCK when locking failed </dd></dl>
 637
 638 </div>
 639 </div><p>
 640 </div>
 641 <hr size="1"><address style="text-align: right;"><small>Generated on Tue Jun 30 14:43:54 2009 for Elektra Projekt by&nbsp;
 642 <a href="http://www.doxygen.org/index.html">
 643 <img src="doxygen.png" alt="doxygen" align="middle" border="0"></a> 1.5.6 </small></address>
 644 </body>
 645 </html>