<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>Elektra Projekt: KDB Backends :: Backend Helper for Elektra</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.1 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1>KDB Backends :: Backend Helper for Elektra</h1>
<p>Backend helper Methods for Elektra and Backends.
<a href="#_details">More...</a></p>
<table border="0" cellpadding="0" cellspacing="0">
<tr><td colspan="2"><h2>Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#gacea5819334a71744a54a6b290a8c3bdc">kdbbWriteLock</a> (FILE *f)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#ga89aa8c310a5720766639c305e643c069">kdbbReadLock</a> (FILE *f)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#gab969d5d25762464c5f719f4f90757fe8">kdbbUnlock</a> (FILE *f)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ssize_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#gaba58d73495f15a309468fd4798539f22">kdbbEncode</a> (void *kdbbDecoded, size_t size, char *returned)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ssize_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#gafc099de90661f22a048d5fd16fca48f5">kdbbDecode</a> (char *kdbbEncoded, void *returned)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#ga11b83ea1eac5adb730c3f51660cded9d">kdbbNeedsUTF8Conversion</a> ()</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#ga5b9a2cb642f2a626037c4c730c790c65">kdbbUTF8Engine</a> (int direction, char **string, size_t *inputOutputByteSize)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#gaac1bda629cb9912eaaaa785b2874cad1">kdbbEncodeChar</a> (char c, char *buffer, size_t bufSize)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#ga0ae368114cb42f6f6d56bc5cc96e44cf">kdbbDecodeChar</a> (const char *from, char *into)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#gae3ac53e11feb9d7ff956a4562f1d9bde">kdbbFilenameToKeyName</a> (const char *string, char *buffer, int bufSize)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ssize_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#ga10364b65d79e44f99f9464e50dffa900">kdbbGetFullKeyName</a> (KDB *handle, const char *forFilename, const Key *parentKey, Key *returned)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">int </td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#ga93921f5f2169e9d6ba1603807ee5bc2d">kdbbKeyNameToRelativeFilename</a> (const char *string, char *buffer, size_t bufSize)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ssize_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#ga1d09dab69a7d6cee9a1eb2c1c650051e">kdbbKeyCalcRelativeFilename</a> (const Key *key, char *relativeFilename, size_t maxSize)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ssize_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__backendhelper.html#ga6db2e7738f905ea0ab52b5c9c3981af6">kdbbGetFullFilename</a> (KDB *handle, const Key *forKey, char *returned, size_t maxSize)</td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<p>Backend helper Methods for Elektra and Backends. </p>
<p>To use them: </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor"> #include <kdbbackend.h></span>
</pre></div><p>These backend helper methods provide functionality commonly used by backends to make backend development easier and to provide the same behaviour between backends. </p>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="gafc099de90661f22a048d5fd16fca48f5"></a><!-- doxytag: member="helper.c::kdbbDecode" ref="gafc099de90661f22a048d5fd16fca48f5" args="(char *kdbbEncoded, void *returned)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t kdbbDecode </td>
<td>(</td>
<td class="paramtype">char * </td>
<td class="paramname"> <em>kdbbEncoded</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"> <em>returned</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>UnkdbbEncodes a buffer of ASCII hexadecimal values into a byte stream.</p>
<p>The allowed format for the hexadecimal values is just a stream of pairs of plain hex-digits, all together or space-separated.</p>
<p>The <code>returned</code> data won't be bigger than half the size of the source <code>kdbbEncoded</code> data.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>kdbbEncoded</em> </td><td>the source of ASCII hexadecimal digits. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>returned</em> </td><td>preallocated destination for the kdbbDecoded data. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the amount of bytes kdbbDecoded </dd>
<dd>
-1 on failure </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__backendhelper.html#gaba58d73495f15a309468fd4798539f22">kdbbEncode()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga0ae368114cb42f6f6d56bc5cc96e44cf"></a><!-- doxytag: member="helper.c::kdbbDecodeChar" ref="ga0ae368114cb42f6f6d56bc5cc96e44cf" args="(const char *from, char *into)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kdbbDecodeChar </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>from</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">char * </td>
<td class="paramname"> <em>into</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Char decoding.</p>
<p>Decode one char from 25, 2B, 2F, 2C following RFC 2396 or copy char untouched if different.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>from</em> </td><td>String containing sequence to decode </td></tr>
<tr><td valign="top"></td><td valign="top"><em>into</em> </td><td>Decoded char </td></tr>
</table>
</dd>
</dl>
<dl class="return"><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>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__backendhelper.html#gaac1bda629cb9912eaaaa785b2874cad1">kdbbEncodeChar</a></dd></dl>
<p>NOTE: No '\0' is added at the end of buffer. </p>
</div>
</div>
<a class="anchor" id="gaba58d73495f15a309468fd4798539f22"></a><!-- doxytag: member="helper.c::kdbbEncode" ref="gaba58d73495f15a309468fd4798539f22" args="(void *kdbbDecoded, size_t size, char *returned)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t kdbbEncode </td>
<td>(</td>
<td class="paramtype">void * </td>
<td class="paramname"> <em>kdbbDecoded</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t </td>
<td class="paramname"> <em>size</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">char * </td>
<td class="paramname"> <em>returned</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Encodes a buffer of data onto hexadecimal ASCII.</p>
<p>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#gafc099de90661f22a048d5fd16fca48f5">kdbbDecode()</a>.</p>
<p>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>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>kdbbDecoded</em> </td><td>the source buffer. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>size</em> </td><td>the size of the source buffer in bytes. </td></tr>
<tr><td valign="top"></td><td valign="top"><em>returned</em> </td><td>the preallocated destination for the ASCII-kdbbEncoded data. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the amount of bytes used in the resulting kdbbEncoded buffer. </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__backendhelper.html#gafc099de90661f22a048d5fd16fca48f5">kdbbDecode()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gaac1bda629cb9912eaaaa785b2874cad1"></a><!-- doxytag: member="helper.c::kdbbEncodeChar" ref="gaac1bda629cb9912eaaaa785b2874cad1" args="(char c, char *buffer, size_t bufSize)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kdbbEncodeChar </td>
<td>(</td>
<td class="paramtype">char </td>
<td class="paramname"> <em>c</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">char * </td>
<td class="paramname"> <em>buffer</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t </td>
<td class="paramname"> <em>bufSize</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Char encoding.</p>
<p>Encode '/', '\', '', '+', ' ' char following RFC 2396 or copy char untouched if different.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>c</em> </td><td>Char to kdbbEncode </td></tr>
<tr><td valign="top"></td><td valign="top"><em>buffer</em> </td><td>string wich will contain kdbbEncoded char </td></tr>
<tr><td valign="top"></td><td valign="top"><em>bufSize</em> </td><td>Size of the buffer </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>: Size of the kdbbEncoded string if success or -1 if error * (then buffer is untouched)</dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd>kdbiDecodeChar</dd></dl>
<p>NOTE: No '\0' is added at the end of buffer. </p>
</div>
</div>
<a class="anchor" id="gae3ac53e11feb9d7ff956a4562f1d9bde"></a><!-- doxytag: member="helper.c::kdbbFilenameToKeyName" ref="gae3ac53e11feb9d7ff956a4562f1d9bde" args="(const char *string, char *buffer, int bufSize)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kdbbFilenameToKeyName </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>string</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">char * </td>
<td class="paramname"> <em>buffer</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"> <em>bufSize</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Translate a relative file name to a key name applying decoding.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>string</em> </td><td>Filename </td></tr>
<tr><td valign="top"></td><td valign="top"><em>buffer</em> </td><td>decoded keyName </td></tr>
<tr><td valign="top"></td><td valign="top"><em>bufSize</em> </td><td>Size of buffer </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd>
<dd>
-1 on failure</dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__backendhelper.html#ga93921f5f2169e9d6ba1603807ee5bc2d">kdbbKeyNameToRelativeFilename</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga6db2e7738f905ea0ab52b5c9c3981af6"></a><!-- doxytag: member="helper.c::kdbbGetFullFilename" ref="ga6db2e7738f905ea0ab52b5c9c3981af6" args="(KDB *handle, const Key *forKey, char *returned, size_t maxSize)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t kdbbGetFullFilename </td>
<td>(</td>
<td class="paramtype">KDB * </td>
<td class="paramname"> <em>handle</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>forKey</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">char * </td>
<td class="paramname"> <em>returned</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t </td>
<td class="paramname"> <em>maxSize</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Calculate the real file name for a key.</p>
<p>system/ keys will get the prefix KDB_DB_SYSTEM</p>
<p>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/<owner>/kdb b.) The home variable in system/users/<owner>/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/<owner>/KDB_DB_USER will be used</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>forKey</em> </td><td>the key object to work with </td></tr>
<tr><td valign="top"></td><td valign="top"><em>handle</em> </td><td>the kdb handle to work with </td></tr>
<tr><td valign="top"></td><td valign="top"><em>returned</em> </td><td>the buffer to return the calculated filename </td></tr>
<tr><td valign="top"></td><td valign="top"><em>maxSize</em> </td><td>maximum number of bytes that fit the buffer </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd>kdbCalcRelativeFilename() </dd></dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>number of bytes written to the buffer, or 0 on error</dd>
<dd>
length of returned string on success </dd>
<dd>
-1 on failure </dd></dl>
</div>
</div>
<a class="anchor" id="ga10364b65d79e44f99f9464e50dffa900"></a><!-- doxytag: member="helper.c::kdbbGetFullKeyName" ref="ga10364b65d79e44f99f9464e50dffa900" args="(KDB *handle, const char *forFilename, const Key *parentKey, Key *returned)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t kdbbGetFullKeyName </td>
<td>(</td>
<td class="paramtype">KDB * </td>
<td class="paramname"> <em>handle</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>forFilename</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>parentKey</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>returned</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Calculates the keyname out of a relative filename.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>handle</em> </td><td>The kdb handle to work with </td></tr>
<tr><td valign="top"></td><td valign="top"><em>forFilename</em> </td><td>needs to be the a null terminated string containing the relative filename </td></tr>
<tr><td valign="top"></td><td valign="top"><em>parentKey</em> </td><td>is the key above the key which will be returned </td></tr>
<tr><td valign="top"></td><td valign="top"><em>returned</em> </td><td>The proper keyname and owner will be stored in returned. A valid key must be passed. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>number of bytes written to the buffer, or 0 on error</dd>
<dd>
length of returned string on success </dd>
<dd>
-1 on failure </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__backendhelper.html#ga93921f5f2169e9d6ba1603807ee5bc2d">kdbbKeyNameToRelativeFilename()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga1d09dab69a7d6cee9a1eb2c1c650051e"></a><!-- doxytag: member="helper.c::kdbbKeyCalcRelativeFilename" ref="ga1d09dab69a7d6cee9a1eb2c1c650051e" args="(const Key *key, char *relativeFilename, size_t maxSize)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t kdbbKeyCalcRelativeFilename </td>
<td>(</td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>key</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">char * </td>
<td class="paramname"> <em>relativeFilename</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t </td>
<td class="paramname"> <em>maxSize</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>This is a helper to kdbGetFullFilename()</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>has the relevant name for the relative filename </td></tr>
<tr><td valign="top"></td><td valign="top"><em>relativeFilename</em> </td><td>the buffer to return the calculated filename </td></tr>
<tr><td valign="top"></td><td valign="top"><em>maxSize</em> </td><td>maximum number of bytes that fit the buffer </td></tr>
</table>
</dd>
</dl>
<dl class="see"><dt><b>See also:</b></dt><dd>kdbGetFullFilename() </dd></dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>number of bytes written to the buffer </dd>
<dd>
-1 on failure </dd></dl>
</div>
</div>
<a class="anchor" id="ga93921f5f2169e9d6ba1603807ee5bc2d"></a><!-- doxytag: member="helper.c::kdbbKeyNameToRelativeFilename" ref="ga93921f5f2169e9d6ba1603807ee5bc2d" args="(const char *string, char *buffer, size_t bufSize)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kdbbKeyNameToRelativeFilename </td>
<td>(</td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>string</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">char * </td>
<td class="paramname"> <em>buffer</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t </td>
<td class="paramname"> <em>bufSize</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Translate a key name to a relative file name applying encoding.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>string</em> </td><td>Keyname </td></tr>
<tr><td valign="top"></td><td valign="top"><em>buffer</em> </td><td>kdbbEncoded filename </td></tr>
<tr><td valign="top"></td><td valign="top"><em>bufSize</em> </td><td>Size of buffer </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>Number of byte written in buffer on success, </dd>
<dd>
-1 on failure</dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__backendhelper.html#ga93921f5f2169e9d6ba1603807ee5bc2d">kdbbKeyNameToRelativeFilename</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga11b83ea1eac5adb730c3f51660cded9d"></a><!-- doxytag: member="helper.c::kdbbNeedsUTF8Conversion" ref="ga11b83ea1eac5adb730c3f51660cded9d" args="()" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kdbbNeedsUTF8Conversion </td>
<td>(</td>
<td class="paramtype">void </td>
<td class="paramname"></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>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#ga5b9a2cb642f2a626037c4c730c790c65">kdbbUTF8Engine()</a> function for more information.</p>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 if not needed </dd>
<dd>
anything else if needed </dd></dl>
</div>
</div>
<a class="anchor" id="ga89aa8c310a5720766639c305e643c069"></a><!-- doxytag: member="helper.c::kdbbReadLock" ref="ga89aa8c310a5720766639c305e643c069" args="(FILE *f)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kdbbReadLock </td>
<td>(</td>
<td class="paramtype">FILE * </td>
<td class="paramname"> <em>f</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Locks file for read mode.</p>
<p>Other processes and threads are allowed to read the file too simultaneous.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>f</em> </td><td>is a valid filedescriptor </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd>
<dd>
-1 on failure</dd></dl>
<dl class="err"><dt><b><a class="el" href="err.html#_err000002">Error:</a></b></dt><dd>sets KDB_ERR_NOLOCK when locking failed </dd></dl>
</div>
</div>
<a class="anchor" id="gab969d5d25762464c5f719f4f90757fe8"></a><!-- doxytag: member="helper.c::kdbbUnlock" ref="gab969d5d25762464c5f719f4f90757fe8" args="(FILE *f)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kdbbUnlock </td>
<td>(</td>
<td class="paramtype">FILE * </td>
<td class="paramname"> <em>f</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Unlocks file.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>f</em> </td><td>is a valid filedescriptor </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd>
<dd>
-1 on failure</dd></dl>
<dl class="err"><dt><b><a class="el" href="err.html#_err000003">Error:</a></b></dt><dd>sets KDB_ERR_NOLOCK when locking failed </dd></dl>
</div>
</div>
<a class="anchor" id="ga5b9a2cb642f2a626037c4c730c790c65"></a><!-- doxytag: member="helper.c::kdbbUTF8Engine" ref="ga5b9a2cb642f2a626037c4c730c790c65" args="(int direction, char **string, size_t *inputOutputByteSize)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kdbbUTF8Engine </td>
<td>(</td>
<td class="paramtype">int </td>
<td class="paramname"> <em>direction</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">char ** </td>
<td class="paramname"> <em>string</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t * </td>
<td class="paramname"> <em>inputOutputByteSize</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Converts string to (<code>direction</code> = <code>UTF8_TO</code>) and from (<code>direction</code> = <code>UTF8_FROM</code>) UTF-8.</p>
<p>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>
<p>Broken locales in applications can cause problems too. Make sure to load the environment locales in your application using </p>
<div class="fragment"><pre class="fragment">setlocale (LC_ALL, <span class="stringliteral">""</span>);
</pre></div><p>Otherwise kdbbUTF8Engine will quit with -1 leading that backends return with error when non-ascii characters appear. Binary values are not effected.</p>
<p>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>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>direction</em> </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>
<tr><td valign="top"></td><td valign="top"><em>string</em> </td><td>before the call: the string to be converted; after the call: reallocated to carry the converted string </td></tr>
<tr><td valign="top"></td><td valign="top"><em>inputOutputByteSize</em> </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>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd>
<dd>
-1 on failure </dd></dl>
</div>
</div>
<a class="anchor" id="gacea5819334a71744a54a6b290a8c3bdc"></a><!-- doxytag: member="helper.c::kdbbWriteLock" ref="gacea5819334a71744a54a6b290a8c3bdc" args="(FILE *f)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">int kdbbWriteLock </td>
<td>(</td>
<td class="paramtype">FILE * </td>
<td class="paramname"> <em>f</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Locks file for exclusive write mode.</p>
<p>This function will block until all reader and writer have left the file.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>f</em> </td><td>is a valid filedescriptor </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>0 on success </dd>
<dd>
-1 on failure</dd></dl>
<dl class="err"><dt><b><a class="el" href="err.html#_err000001">Error:</a></b></dt><dd>sets KDB_ERR_NOLOCK when locking failed </dd></dl>
</div>
</div>
</div>
<hr size="1"/><address style="text-align: right;"><small>Generated on 8 Nov 2009 for Elektra Projekt by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.1 </small></address>
</body>
</html>
