<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>Elektra Projekt: Key :: Value Manipulation Methods</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.6.1 -->
<div class="navigation" id="top">
<div class="tabs">
<ul>
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
</ul>
</div>
</div>
<div class="contents">
<h1>Key :: Value Manipulation Methods</h1>
<p>Methods to do various operations on Key values.
<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">const void * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyvalue.html#ga6f29609c5da53c6dc26a98678d5752af">keyValue</a> (const Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ssize_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyvalue.html#gae326672fffb7474abfe9baf53b73217e">keyGetValueSize</a> (const Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ssize_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyvalue.html#ga41b9fac5ccddafe407fc0ae1e2eb8778">keyGetString</a> (const Key *key, char *returnedString, 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__keyvalue.html#ga622bde1eb0e0c4994728331326340ef2">keySetString</a> (Key *key, const char *newStringValue)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ssize_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyvalue.html#ga4c0d8a4a11174197699c231e0b5c3c84">keyGetBinary</a> (const Key *key, void *returnedBinary, 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__keyvalue.html#gaa50a5358fd328d373a45f395fa1b99e7">keySetBinary</a> (Key *key, const void *newBinary, size_t dataSize)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">const char * </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyvalue.html#gac89fd319783b3457db45b4c09e55274a">keyComment</a> (const Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ssize_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyvalue.html#ga0dd737fadc16d4cf16720d17f066a9d3">keyGetCommentSize</a> (const Key *key)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">ssize_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group__keyvalue.html#gafb89735689929ff717cc9f2d0d0b46a2">keyGetComment</a> (const Key *key, char *returnedComment, 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__keyvalue.html#ga8863a877a84fa46e6017fe72e49b89c1">keySetComment</a> (Key *key, const char *newComment)</td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<p>Methods to do various operations on Key values. </p>
<p>A key can contain a value in different format. The most likely situation is, that the value is interpreted as text. Use <a class="el" href="group__keyvalue.html#ga41b9fac5ccddafe407fc0ae1e2eb8778">keyGetString()</a> for that. You can save any Unicode Symbols and Elektra will take care that you get the same back, independent of your current environment.</p>
<p>In some situations this idea fails. When you need exactly the same value back without any interpretation of the characters, there is <a class="el" href="group__keyvalue.html#gaa50a5358fd328d373a45f395fa1b99e7">keySetBinary()</a>. If you use that, its very likely that your Configuration is not according to the standard. Also for Numbers, Booleans and Date you should use <a class="el" href="group__keyvalue.html#ga41b9fac5ccddafe407fc0ae1e2eb8778">keyGetString()</a>. To do so, you might use strtod() strtol() and then atol() or atof() to convert back.</p>
<p>To use them: </p>
<div class="fragment"><pre class="fragment"><span class="preprocessor">#include <kdb.h></span>
</pre></div> <hr/><h2>Function Documentation</h2>
<a class="anchor" id="gac89fd319783b3457db45b4c09e55274a"></a><!-- doxytag: member="keyvalue.c::keyComment" ref="gac89fd319783b3457db45b4c09e55274a" args="(const Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">const char* keyComment </td>
<td>(</td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Return a pointer to the real internal <code>key</code> comment.</p>
<p>This is a much more efficient version of <a class="el" href="group__keyvalue.html#gafb89735689929ff717cc9f2d0d0b46a2">keyGetComment()</a> and you should use it if you are responsible enough to not mess up things. You are not allowed to change anything in the memory region the returned pointer points to.</p>
<p><a class="el" href="group__keyvalue.html#gac89fd319783b3457db45b4c09e55274a">keyComment()</a> returns "" when there is no keyComment. The reason is </p>
<div class="fragment"><pre class="fragment">key=<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0);
<a class="code" href="group__keyvalue.html#ga8863a877a84fa46e6017fe72e49b89c1">keySetComment</a>(key,<span class="stringliteral">""</span>);
<a class="code" href="group__keyvalue.html#gac89fd319783b3457db45b4c09e55274a">keyComment</a>(key); <span class="comment">// you would expect "" here</span>
<a class="code" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel</a>(key);
</pre></div><p>See <a class="el" href="group__keyvalue.html#ga8863a877a84fa46e6017fe72e49b89c1">keySetComment()</a> for more information on comments.</p>
<dl class="note"><dt><b>Note:</b></dt><dd>Note that the Key structure keeps its own size field that is calculated by library internal calls, so to avoid inconsistencies, you must never use the pointer returned by <a class="el" href="group__keyvalue.html#gac89fd319783b3457db45b4c09e55274a">keyComment()</a> method to set a new value. Use <a class="el" href="group__keyvalue.html#ga8863a877a84fa46e6017fe72e49b89c1">keySetComment()</a> instead.</dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>a pointer to the internal managed comment </dd>
<dd>
"" when there is no comment </dd>
<dd>
0 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyvalue.html#ga0dd737fadc16d4cf16720d17f066a9d3">keyGetCommentSize()</a> for size and <a class="el" href="group__keyvalue.html#gafb89735689929ff717cc9f2d0d0b46a2">keyGetComment()</a> as alternative </dd></dl>
</div>
</div>
<a class="anchor" id="ga4c0d8a4a11174197699c231e0b5c3c84"></a><!-- doxytag: member="keyvalue.c::keyGetBinary" ref="ga4c0d8a4a11174197699c231e0b5c3c84" args="(const Key *key, void *returnedBinary, size_t maxSize)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t keyGetBinary </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">void * </td>
<td class="paramname"> <em>returnedBinary</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>Get the value of a key as a binary.</p>
<p>If the type is not binary -1 will be returned.</p>
<p>When the binary data is empty (this is not the same as ""!) 0 will be returned and the returnedBinary will not be changed.</p>
<p>For string values see <a class="el" href="group__keyvalue.html#ga41b9fac5ccddafe407fc0ae1e2eb8778">keyGetString()</a> and <a class="el" href="group__keytest.html#gaea7670778abd07fee0fe8ac12a149190">keyIsString()</a>.</p>
<p>When the returnedBinary is to small to hold the data (its maximum size is given by maxSize), the returnedBinary will not be changed and -1 is returned.</p>
<dl class="user"><dt><b>Example:</b></dt><dd><div class="fragment"><pre class="fragment">Key *key = <a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a> (<span class="stringliteral">"user/keyname"</span>, KEY_TYPE, KEY_TYPE_BINARY, KEY_END);
<span class="keywordtype">char</span> buffer[300];
<span class="keywordflow">if</span> (<a class="code" href="group__keyvalue.html#ga4c0d8a4a11174197699c231e0b5c3c84">keyGetBinary</a>(key,buffer,<span class="keyword">sizeof</span>(buffer)) == -1)
{
<span class="comment">// handle error</span>
}
</pre></div></dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the object to gather the value from </td></tr>
<tr><td valign="top"></td><td valign="top"><em>returnedBinary</em> </td><td>pre-allocated memory to store a copy of the key value </td></tr>
<tr><td valign="top"></td><td valign="top"><em>maxSize</em> </td><td>number of bytes of pre-allocated memory in <code>returnedBinary</code> </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the number of bytes actually copied to <code>returnedBinary</code> </dd>
<dd>
0 if the binary is empty </dd>
<dd>
-1 on NULL pointers </dd>
<dd>
-1 when maxSize is 0, too small to hold the value or larger than SSIZE_MAX </dd>
<dd>
-1 on typing error when the key is not binary </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyvalue.html#ga6f29609c5da53c6dc26a98678d5752af">keyValue()</a>, <a class="el" href="group__keyvalue.html#gae326672fffb7474abfe9baf53b73217e">keyGetValueSize()</a>, <a class="el" href="group__keyvalue.html#gaa50a5358fd328d373a45f395fa1b99e7">keySetBinary()</a> </dd>
<dd>
<a class="el" href="group__keyvalue.html#ga41b9fac5ccddafe407fc0ae1e2eb8778">keyGetString()</a> and <a class="el" href="group__keyvalue.html#ga622bde1eb0e0c4994728331326340ef2">keySetString()</a> as preferred alternative to binary </dd>
<dd>
<a class="el" href="group__keytest.html#ga9526b371087564e43e3dff8ad0dac949">keyIsBinary()</a> to see how to check for binary type </dd></dl>
</div>
</div>
<a class="anchor" id="gafb89735689929ff717cc9f2d0d0b46a2"></a><!-- doxytag: member="keyvalue.c::keyGetComment" ref="gafb89735689929ff717cc9f2d0d0b46a2" args="(const Key *key, char *returnedComment, size_t maxSize)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t keyGetComment </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>returnedComment</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>Get the key comment.</p>
<h2><a class="anchor" id="comment">
Comments</a></h2>
<p>A Key comment is description for humans what this key is for. It may be a textual explanation of valid values, when and why a user or administrator changed the key or any other text that helps the user or administrator related to that key.</p>
<p>Don't depend on a comment in your program. A user is always allowed to remove or change it in any way he wants to. But you are allowed or even encouraged to always show the content of the comment to the user and allow him to change it.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to work with </td></tr>
<tr><td valign="top"></td><td valign="top"><em>returnedComment</em> </td><td>pre-allocated memory to copy the comments to </td></tr>
<tr><td valign="top"></td><td valign="top"><em>maxSize</em> </td><td>number of bytes that will fit returnedComment </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the number of bytes actually copied to <code>returnedString</code>, including final NULL </dd>
<dd>
1 if the string is empty </dd>
<dd>
-1 on NULL pointer </dd>
<dd>
-1 if maxSize is 0, not enough to store the comment or when larger then SSIZE_MAX </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyvalue.html#ga0dd737fadc16d4cf16720d17f066a9d3">keyGetCommentSize()</a>, <a class="el" href="group__keyvalue.html#ga8863a877a84fa46e6017fe72e49b89c1">keySetComment()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga0dd737fadc16d4cf16720d17f066a9d3"></a><!-- doxytag: member="keyvalue.c::keyGetCommentSize" ref="ga0dd737fadc16d4cf16720d17f066a9d3" args="(const Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t keyGetCommentSize </td>
<td>(</td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Calculates number of bytes needed to store a key comment, including final NULL.</p>
<p>Use this method to know to size for allocated memory to retrieve a key comment.</p>
<p>See <a class="el" href="group__keyvalue.html#ga8863a877a84fa46e6017fe72e49b89c1">keySetComment()</a> for more information on comments.</p>
<p>For an empty key name you need one byte to store the ending NULL. For that reason 1 is returned.</p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">char</span> *buffer;
buffer = malloc (<a class="code" href="group__keyvalue.html#ga0dd737fadc16d4cf16720d17f066a9d3">keyGetCommentSize</a> (key));
<span class="comment">// use this buffer to store the comment</span>
<span class="comment">// pass keyGetCommentSize (key) for maxSize</span>
</pre></div><dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>number of bytes needed </dd>
<dd>
1 if there is no comment </dd>
<dd>
-1 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyvalue.html#gafb89735689929ff717cc9f2d0d0b46a2">keyGetComment()</a>, <a class="el" href="group__keyvalue.html#ga8863a877a84fa46e6017fe72e49b89c1">keySetComment()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga41b9fac5ccddafe407fc0ae1e2eb8778"></a><!-- doxytag: member="keyvalue.c::keyGetString" ref="ga41b9fac5ccddafe407fc0ae1e2eb8778" args="(const Key *key, char *returnedString, size_t maxSize)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t keyGetString </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>returnedString</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>Get the value of a key as a string.</p>
<p>When there is no value inside the string, 1 will be returned and the returnedString will be empty "" to avoid programming errors that old strings are shown to the user.</p>
<p>For binary values see <a class="el" href="group__keyvalue.html#ga4c0d8a4a11174197699c231e0b5c3c84">keyGetBinary()</a> and <a class="el" href="group__keytest.html#ga9526b371087564e43e3dff8ad0dac949">keyIsBinary()</a>.</p>
<dl class="user"><dt><b>Example:</b></dt><dd><div class="fragment"><pre class="fragment">Key *key = <a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a> (<span class="stringliteral">"user/keyname"</span>, KEY_END);
<span class="keywordtype">char</span> buffer[300];
<span class="keywordflow">if</span> (<a class="code" href="group__keyvalue.html#ga41b9fac5ccddafe407fc0ae1e2eb8778">keyGetString</a>(key,buffer,<span class="keyword">sizeof</span>(buffer)) == -1)
{
<span class="comment">// handle error</span>
} <span class="keywordflow">else</span> {
printf (<span class="stringliteral">"buffer: %s\n"</span>, buffer);
}
</pre></div></dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the object to gather the value from </td></tr>
<tr><td valign="top"></td><td valign="top"><em>returnedString</em> </td><td>pre-allocated memory to store a copy of the key value </td></tr>
<tr><td valign="top"></td><td valign="top"><em>maxSize</em> </td><td>number of bytes of allocated memory in <code>returnedString</code> </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the number of bytes actually copied to <code>returnedString</code>, including final NULL </dd>
<dd>
1 if the string is empty </dd>
<dd>
-1 on NULL pointer </dd>
<dd>
-1 on type mismatch </dd>
<dd>
maxSize is 0, too small for string or is larger than SSIZE_MAX </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyvalue.html#ga6f29609c5da53c6dc26a98678d5752af">keyValue()</a>, <a class="el" href="group__keyvalue.html#gae326672fffb7474abfe9baf53b73217e">keyGetValueSize()</a>, <a class="el" href="group__keyvalue.html#ga622bde1eb0e0c4994728331326340ef2">keySetString()</a> </dd>
<dd>
<a class="el" href="group__keyvalue.html#ga4c0d8a4a11174197699c231e0b5c3c84">keyGetBinary()</a> for working with binary data </dd></dl>
</div>
</div>
<a class="anchor" id="gae326672fffb7474abfe9baf53b73217e"></a><!-- doxytag: member="keyvalue.c::keyGetValueSize" ref="gae326672fffb7474abfe9baf53b73217e" args="(const Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t keyGetValueSize </td>
<td>(</td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Returns the number of bytes needed to store the key value, including the NULL terminator.</p>
<p>It returns the correct size, independent of the Key Type. If it is a binary there might be '\0' values in it.</p>
<p>For an empty string you need one byte to store the ending NULL. For that reason 1 is returned. This is not true for binary data, so there might be returned 0 too.</p>
<p>A binary key has no '\0' termination. String types have it, so to there length will be added 1 to have enough space to store it.</p>
<p>This method can be used with malloc() before <a class="el" href="group__keyvalue.html#ga41b9fac5ccddafe407fc0ae1e2eb8778">keyGetString()</a> or <a class="el" href="group__keyvalue.html#ga4c0d8a4a11174197699c231e0b5c3c84">keyGetBinary()</a> is called.</p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">char</span> *buffer;
buffer = malloc (<a class="code" href="group__keyvalue.html#gae326672fffb7474abfe9baf53b73217e">keyGetValueSize</a> (key));
<span class="comment">// use this buffer to store the value (binary or string)</span>
<span class="comment">// pass keyGetValueSize (key) for maxSize</span>
</pre></div><dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the number of bytes needed to store the key value </dd>
<dd>
1 when there is no data and type is not binary </dd>
<dd>
0 when there is no data and type is binary </dd>
<dd>
-1 on null pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyvalue.html#ga41b9fac5ccddafe407fc0ae1e2eb8778">keyGetString()</a>, <a class="el" href="group__keyvalue.html#ga4c0d8a4a11174197699c231e0b5c3c84">keyGetBinary()</a>, <a class="el" href="group__keyvalue.html#ga6f29609c5da53c6dc26a98678d5752af">keyValue()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="gaa50a5358fd328d373a45f395fa1b99e7"></a><!-- doxytag: member="keyvalue.c::keySetBinary" ref="gaa50a5358fd328d373a45f395fa1b99e7" args="(Key *key, const void *newBinary, size_t dataSize)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t keySetBinary </td>
<td>(</td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>key</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const void * </td>
<td class="paramname"> <em>newBinary</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">size_t </td>
<td class="paramname"> <em>dataSize</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Set the value of a key as a binary.</p>
<p>A private copy of <code>newBinary</code> will allocated and saved inside <code>key</code>, so the parameter can be deallocated after the call.</p>
<p>The <code>filesys</code> backend, when used through a <a class="el" href="group__kdbhighlevel.html#ga23b2f5fead4cddeb5542051a197ddc20">kdbSetKey()</a>, will make the value be kdbbEncoded into a human readable hex-digit text format.</p>
<p>Consider using a string key instead.</p>
<p>When newBinary is a NULL pointer the binary will be freed and 0 will be returned.</p>
<dl class="note"><dt><b>Note:</b></dt><dd>When the type of the key is already a binary type it won't be changed.</dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the object on which to set the value </td></tr>
<tr><td valign="top"></td><td valign="top"><em>newBinary</em> </td><td>is a pointer to any binary data or NULL to free the previous set data </td></tr>
<tr><td valign="top"></td><td valign="top"><em>dataSize</em> </td><td>number of bytes to copy from <code>newBinary</code> </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the number of bytes actually copied to internal struct storage </dd>
<dd>
0 when the internal binary was freed </dd>
<dd>
-1 on NULL pointer </dd>
<dd>
-1 when dataSize is 0 (but newBinary not NULL) or larger than SSIZE_MAX </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyvalue.html#ga4c0d8a4a11174197699c231e0b5c3c84">keyGetBinary()</a> </dd>
<dd>
<a class="el" href="group__keytest.html#ga9526b371087564e43e3dff8ad0dac949">keyIsBinary()</a> to check if the type is binary </dd>
<dd>
<a class="el" href="group__keyvalue.html#ga41b9fac5ccddafe407fc0ae1e2eb8778">keyGetString()</a> and <a class="el" href="group__keyvalue.html#ga622bde1eb0e0c4994728331326340ef2">keySetString()</a> as preferred alternative to binary </dd></dl>
</div>
</div>
<a class="anchor" id="ga8863a877a84fa46e6017fe72e49b89c1"></a><!-- doxytag: member="keyvalue.c::keySetComment" ref="ga8863a877a84fa46e6017fe72e49b89c1" args="(Key *key, const char *newComment)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t keySetComment </td>
<td>(</td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>key</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>newComment</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Set a comment for a key.</p>
<p>A key comment is like a configuration file comment. See <a class="el" href="group__keyvalue.html#ga8863a877a84fa46e6017fe72e49b89c1">keySetComment()</a> for more information.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to work with </td></tr>
<tr><td valign="top"></td><td valign="top"><em>newComment</em> </td><td>the comment, that can be freed after this call. </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the number of bytes actually saved including final NULL </dd>
<dd>
1 when the comment was freed </dd>
<dd>
-1 on NULL pointer or memory problems </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyvalue.html#gafb89735689929ff717cc9f2d0d0b46a2">keyGetComment()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga622bde1eb0e0c4994728331326340ef2"></a><!-- doxytag: member="keyvalue.c::keySetString" ref="ga622bde1eb0e0c4994728331326340ef2" args="(Key *key, const char *newStringValue)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">ssize_t keySetString </td>
<td>(</td>
<td class="paramtype">Key * </td>
<td class="paramname"> <em>key</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">const char * </td>
<td class="paramname"> <em>newStringValue</em></td><td> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Set the value for <code>key</code> as <code>newStringValue</code>.</p>
<p>The function will allocate and save a private copy of <code>newStringValue</code>, so the parameter can be freed after the call.</p>
<p>String values will be saved in backend storage, when <a class="el" href="group__kdbhighlevel.html#ga23b2f5fead4cddeb5542051a197ddc20">kdbSetKey()</a> will be called, in UTF-8 universal encoding, regardless of the program's current encoding, when compiled with --enable-iconv.</p>
<p>The type will be set to KEY_TYPE_STRING. When the type of the key is already a string type it won't be changed.</p>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key to set the string value </td></tr>
<tr><td valign="top"></td><td valign="top"><em>newStringValue</em> </td><td>NULL-terminated text string to be set as <code>key's</code> value </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>the number of bytes actually saved in private struct including final NULL </dd>
<dd>
-1 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyvalue.html#ga41b9fac5ccddafe407fc0ae1e2eb8778">keyGetString()</a>, <a class="el" href="group__keyvalue.html#ga6f29609c5da53c6dc26a98678d5752af">keyValue()</a> </dd></dl>
</div>
</div>
<a class="anchor" id="ga6f29609c5da53c6dc26a98678d5752af"></a><!-- doxytag: member="keyvalue.c::keyValue" ref="ga6f29609c5da53c6dc26a98678d5752af" args="(const Key *key)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">const void* keyValue </td>
<td>(</td>
<td class="paramtype">const Key * </td>
<td class="paramname"> <em>key</em></td>
<td> ) </td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Return a pointer to the real internal <code>key</code> value.</p>
<p>This is a much more efficient version of <a class="el" href="group__keyvalue.html#ga41b9fac5ccddafe407fc0ae1e2eb8778">keyGetString()</a> <a class="el" href="group__keyvalue.html#ga4c0d8a4a11174197699c231e0b5c3c84">keyGetBinary()</a>, and you should use it if you are responsible enough to not mess up things. You are not allowed to modify anything in the returned string. If you need a copy of the Value, consider to use <a class="el" href="group__keyvalue.html#ga41b9fac5ccddafe407fc0ae1e2eb8778">keyGetString()</a> or <a class="el" href="group__keyvalue.html#ga4c0d8a4a11174197699c231e0b5c3c84">keyGetBinary()</a> instead.</p>
<h2><a class="anchor" id="string">
String Handling</a></h2>
<p>If <code>key</code> is string (<a class="el" href="group__keytest.html#gaea7670778abd07fee0fe8ac12a149190">keyIsString()</a>), you may cast the returned as a <code>"char *"</code> because you'll get a NULL terminated regular string.</p>
<p><a class="el" href="group__keyvalue.html#ga6f29609c5da53c6dc26a98678d5752af">keyValue()</a> returns "" in string mode when there is no value. The reason is </p>
<div class="fragment"><pre class="fragment">key=<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0);
<a class="code" href="group__keyvalue.html#ga622bde1eb0e0c4994728331326340ef2">keySetString</a>(key,<span class="stringliteral">""</span>);
<a class="code" href="group__keyvalue.html#ga6f29609c5da53c6dc26a98678d5752af">keyValue</a>(key); <span class="comment">// you would expect "" here</span>
<a class="code" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel</a>(key);
</pre></div><h2><a class="anchor" id="binary">
Binary Data Handling</a></h2>
<p>If the data is binary, the size of the value must be determined by <a class="el" href="group__keyvalue.html#gae326672fffb7474abfe9baf53b73217e">keyGetValueSize()</a>, any strlen() operations are not suitable to determine the size.</p>
<p><a class="el" href="group__keyvalue.html#ga6f29609c5da53c6dc26a98678d5752af">keyValue()</a> returns 0 in binary mode when there is no value. The reason is </p>
<div class="fragment"><pre class="fragment"><span class="keywordtype">int</span> i=23;
key=<a class="code" href="group__key.html#gaf6893c038b3ebee90c73a9ea8356bebf">keyNew</a>(0);
<a class="code" href="group__keyvalue.html#gaa50a5358fd328d373a45f395fa1b99e7">keySetBinary</a>(key, 0, 0);
<a class="code" href="group__keyvalue.html#ga6f29609c5da53c6dc26a98678d5752af">keyValue</a>(key); <span class="comment">// you would expect 0 here</span>
<a class="code" href="group__keyvalue.html#gaa50a5358fd328d373a45f395fa1b99e7">keySetBinary</a>(key,<span class="stringliteral">""</span>, 1);
<a class="code" href="group__keyvalue.html#ga6f29609c5da53c6dc26a98678d5752af">keyValue</a>(key); <span class="comment">// you would expect "" (a pointer to '\0') here</span>
<a class="code" href="group__keyvalue.html#gaa50a5358fd328d373a45f395fa1b99e7">keySetBinary</a>(key, (<span class="keywordtype">void</span>*)&i, 4);
(<span class="keywordtype">int</span>*)<a class="code" href="group__keyvalue.html#ga6f29609c5da53c6dc26a98678d5752af">keyValue</a>(key); <span class="comment">// you would expect a pointer to (int)23 here</span>
<a class="code" href="group__key.html#ga3df95bbc2494e3e6703ece5639be5bb1">keyDel</a>(key);
</pre></div><dl class="note"><dt><b>Note:</b></dt><dd>Note that the Key structure keeps its own size field that is calculated by library internal calls, so to avoid inconsistencies, you must never use the pointer returned by <a class="el" href="group__keyvalue.html#ga6f29609c5da53c6dc26a98678d5752af">keyValue()</a> method to set a new value. Use <a class="el" href="group__keyvalue.html#ga622bde1eb0e0c4994728331326340ef2">keySetString()</a> or <a class="el" href="group__keyvalue.html#gaa50a5358fd328d373a45f395fa1b99e7">keySetBinary()</a> instead.</dd></dl>
<dl class="warning"><dt><b>Warning:</b></dt><dd>Binary keys will return a NULL pointer when there is no data in contrast to <a class="el" href="group__keyname.html#ga8e805c726a60da921d3736cda7813513">keyName()</a>, <a class="el" href="group__keyname.html#gaaff35e7ca8af5560c47e662ceb9465f5">keyBaseName()</a>, <a class="el" href="group__keyname.html#gaf6485fb8599714b6bbd830cf915ffea5">keyOwner()</a> and <a class="el" href="group__keyvalue.html#gac89fd319783b3457db45b4c09e55274a">keyComment()</a>. For string value the behaviour is the same.</dd></dl>
<dl class="user"><dt><b>Example:</b></dt><dd><div class="fragment"><pre class="fragment">KDB *handle = <a class="code" href="group__kdb.html#gab7be60c387892d2235907836c5060e1f">kdbOpen</a>();
KeySet *ks=<a class="code" href="group__keyset.html#ga671e1aaee3ae9dc13b4834a4ddbd2c3c">ksNew</a>(0);
Key *current=0;
<a class="code" href="group__kdbhighlevel.html#ga3013d5768bbcf3c34652f489151940e2">kdbGetByName</a>(handle,ks,<span class="stringliteral">"system/sw/my"</span>,KDB_O_SORT|KDB_O_RECURSIVE);
<a class="code" href="group__keyset.html#gabe793ff51f1728e3429c84a8a9086b70">ksRewind</a>(ks);
<span class="keywordflow">while</span>(current=<a class="code" href="group__keyset.html#ga317321c9065b5a4b3e33fe1c399bcec9">ksNext</a>(ks)) {
<span class="keywordtype">size_t</span> size=0;
<span class="keywordflow">if</span> (keyIsBin(current)) {
size=<a class="code" href="group__keyvalue.html#gae326672fffb7474abfe9baf53b73217e">keyGetValueSize</a>(current);
printf(<span class="stringliteral">"Key %s has a value of size %d bytes. Value: <BINARY>\nComment: %s"</span>,
<a class="code" href="group__keyname.html#ga8e805c726a60da921d3736cda7813513">keyName</a>(current),
size,
<a class="code" href="group__keyvalue.html#gac89fd319783b3457db45b4c09e55274a">keyComment</a>(current));
} <span class="keywordflow">else</span> {
size=<a class="code" href="group__internal.html#gaa13b38e07d4e54738b951c3e0bef2faf">kdbiStrLen</a>((<span class="keywordtype">char</span> *)<a class="code" href="group__keyvalue.html#ga6f29609c5da53c6dc26a98678d5752af">keyValue</a>(current));
printf(<span class="stringliteral">"Key %s has a value of size %d bytes. Value: %s\nComment: %s"</span>,
<a class="code" href="group__keyname.html#ga8e805c726a60da921d3736cda7813513">keyName</a>(current),
size,
(<span class="keywordtype">char</span> *)<a class="code" href="group__keyvalue.html#ga6f29609c5da53c6dc26a98678d5752af">keyValue</a>(current),
<a class="code" href="group__keyvalue.html#gac89fd319783b3457db45b4c09e55274a">keyComment</a>(current));
}
}
<a class="code" href="group__keyset.html#ga27e5c16473b02a422238c8d970db7ac8">ksDel</a> (ks);
<a class="code" href="group__kdb.html#gad9bb8bd3f1296bfa77cc9a1b41b7a859">kdbClose</a> (handle);
</pre></div></dd></dl>
<dl><dt><b>Parameters:</b></dt><dd>
<table border="0" cellspacing="2" cellpadding="0">
<tr><td valign="top"></td><td valign="top"><em>key</em> </td><td>the key object to work with </td></tr>
</table>
</dd>
</dl>
<dl class="return"><dt><b>Returns:</b></dt><dd>a pointer to internal value </dd>
<dd>
"" when there is no data and key is not binary </dd>
<dd>
0 where there is no data and key is binary </dd>
<dd>
0 on NULL pointer </dd></dl>
<dl class="see"><dt><b>See also:</b></dt><dd><a class="el" href="group__keyvalue.html#gae326672fffb7474abfe9baf53b73217e">keyGetValueSize()</a>, <a class="el" href="group__keyvalue.html#ga41b9fac5ccddafe407fc0ae1e2eb8778">keyGetString()</a>, <a class="el" href="group__keyvalue.html#ga4c0d8a4a11174197699c231e0b5c3c84">keyGetBinary()</a> </dd></dl>
</div>
</div>
</div>
<hr size="1"/><address style="text-align: right;"><small>Generated on 8 Nov 2009 for Elektra Projekt by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.1 </small></address>
</body>
</html>
