doc/elektra-api/latex/group__keyvalue.tex

   1 \section{Key :: Value Manipulation Methods}
   2 \label{group__keyvalue}\index{Key :: Value Manipulation Methods@{Key :: Value Manipulation Methods}}
   3 Methods to do various operations on Key values.
   4 \subsection*{Functions}
   5 \begin{CompactItemize}
   6 \item
   7 const void $\ast$ {\bf keyValue} (const Key $\ast$key)
   8 \item
   9 ssize\_\-t {\bf keyGetValueSize} (const Key $\ast$key)
  10 \item
  11 ssize\_\-t {\bf keyGetString} (const Key $\ast$key, char $\ast$returnedString, size\_\-t maxSize)
  12 \item
  13 ssize\_\-t {\bf keySetString} (Key $\ast$key, const char $\ast$newStringValue)
  14 \item
  15 ssize\_\-t {\bf keyGetBinary} (const Key $\ast$key, void $\ast$returnedBinary, size\_\-t maxSize)
  16 \item
  17 ssize\_\-t {\bf keySetBinary} (Key $\ast$key, const void $\ast$newBinary, size\_\-t dataSize)
  18 \item
  19 const char $\ast$ {\bf keyComment} (const Key $\ast$key)
  20 \item
  21 ssize\_\-t {\bf keyGetCommentSize} (const Key $\ast$key)
  22 \item
  23 ssize\_\-t {\bf keyGetComment} (const Key $\ast$key, char $\ast$returnedComment, size\_\-t maxSize)
  24 \item
  25 ssize\_\-t {\bf keySetComment} (Key $\ast$key, const char $\ast$newComment)
  26 \end{CompactItemize}
  27
  28
  29 \subsection{Detailed Description}
  30 Methods to do various operations on Key values.
  31
  32 A key can contain a value in different format. The most likely situation is, that the value is interpreted as text. Use \doxyref{keyGetString()}{p.}{group__keyvalue_g41b9fac5ccddafe407fc0ae1e2eb8778} for that. You can save any Unicode Symbols and Elektra will take care that you get the same back, independent of your current environment.
  33
  34 In some situations this idea fails. When you need exactly the same value back without any interpretation of the characters, there is \doxyref{keySetBinary()}{p.}{group__keyvalue_ga50a5358fd328d373a45f395fa1b99e7}. 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 \doxyref{keyGetString()}{p.}{group__keyvalue_g41b9fac5ccddafe407fc0ae1e2eb8778}. To do so, you might use strtod() strtol() and then atol() or atof() to convert back.
  35
  36 To use them:
  37
  38 \begin{Code}\begin{verbatim}#include <kdb.h>
  39 \end{verbatim}
  40 \end{Code}
  41
  42
  43
  44 \subsection{Function Documentation}
  45 \index{keyvalue@{keyvalue}!keyComment@{keyComment}}
  46 \index{keyComment@{keyComment}!keyvalue@{keyvalue}}
  47 \subsubsection[keyComment]{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ keyComment (const Key $\ast$ {\em key})}\label{group__keyvalue_gc89fd319783b3457db45b4c09e55274a}
  48
  49
  50 Return a pointer to the real internal {\tt key} comment.
  51
  52 This is a much more efficient version of \doxyref{keyGetComment()}{p.}{group__keyvalue_gfb89735689929ff717cc9f2d0d0b46a2} 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.
  53
  54 \doxyref{keyComment()}{p.}{group__keyvalue_gc89fd319783b3457db45b4c09e55274a} returns \char`\"{}\char`\"{} when there is no keyComment. The reason is
  55
  56 \begin{Code}\begin{verbatim}key=keyNew(0);
  57 keySetComment(key,"");
  58 keyComment(key); // you would expect "" here
  59 keyDel(key);
  60 \end{verbatim}
  61 \end{Code}
  62
  63
  64
  65 See \doxyref{keySetComment()}{p.}{group__keyvalue_g8863a877a84fa46e6017fe72e49b89c1} for more information on comments.
  66
  67 \begin{Desc}
  68 \item[Note:]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 \doxyref{keyComment()}{p.}{group__keyvalue_gc89fd319783b3457db45b4c09e55274a} method to set a new value. Use \doxyref{keySetComment()}{p.}{group__keyvalue_g8863a877a84fa46e6017fe72e49b89c1} instead.\end{Desc}
  69 \begin{Desc}
  70 \item[Parameters:]
  71 \begin{description}
  72 \item[{\em key}]the key object to work with \end{description}
  73 \end{Desc}
  74 \begin{Desc}
  75 \item[Returns:]a pointer to the internal managed comment
  76
  77 \char`\"{}\char`\"{} when there is no comment
  78
  79 0 on NULL pointer \end{Desc}
  80 \begin{Desc}
  81 \item[See also:]\doxyref{keyGetCommentSize()}{p.}{group__keyvalue_g0dd737fadc16d4cf16720d17f066a9d3} for size and \doxyref{keyGetComment()}{p.}{group__keyvalue_gfb89735689929ff717cc9f2d0d0b46a2} as alternative \end{Desc}
  82 \index{keyvalue@{keyvalue}!keyGetBinary@{keyGetBinary}}
  83 \index{keyGetBinary@{keyGetBinary}!keyvalue@{keyvalue}}
  84 \subsubsection[keyGetBinary]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetBinary (const Key $\ast$ {\em key}, \/  void $\ast$ {\em returnedBinary}, \/  size\_\-t {\em maxSize})}\label{group__keyvalue_g4c0d8a4a11174197699c231e0b5c3c84}
  85
  86
  87 Get the value of a key as a binary.
  88
  89 If the type is not binary -1 will be returned.
  90
  91 When the binary data is empty (this is not the same as \char`\"{}\char`\"{}!) 0 will be returned and the returnedBinary will not be changed.
  92
  93 For string values see \doxyref{keyGetString()}{p.}{group__keyvalue_g41b9fac5ccddafe407fc0ae1e2eb8778} and \doxyref{keyIsString()}{p.}{group__keytest_gea7670778abd07fee0fe8ac12a149190}.
  94
  95 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.
  96
  97 \begin{Desc}
  98 \item[Example:]
  99
 100 \begin{Code}\begin{verbatim}Key *key = keyNew ("user/keyname", KEY_TYPE, KEY_TYPE_BINARY, KEY_END);
 101 char buffer[300];
 102
 103 if (keyGetBinary(key,buffer,sizeof(buffer)) == -1)
 104 {
 105         // handle error
 106 }
 107 \end{verbatim}
 108 \end{Code}
 109
 110 \end{Desc}
 111 \begin{Desc}
 112 \item[Parameters:]
 113 \begin{description}
 114 \item[{\em key}]the object to gather the value from \item[{\em returnedBinary}]pre-allocated memory to store a copy of the key value \item[{\em maxSize}]number of bytes of pre-allocated memory in {\tt returnedBinary} \end{description}
 115 \end{Desc}
 116 \begin{Desc}
 117 \item[Returns:]the number of bytes actually copied to {\tt returnedBinary}
 118
 119 0 if the binary is empty
 120
 121 -1 on NULL pointers
 122
 123 -1 when maxSize is 0, too small to hold the value or larger than SSIZE\_\-MAX
 124
 125 -1 on typing error when the key is not binary \end{Desc}
 126 \begin{Desc}
 127 \item[See also:]\doxyref{keyValue()}{p.}{group__keyvalue_g6f29609c5da53c6dc26a98678d5752af}, \doxyref{keyGetValueSize()}{p.}{group__keyvalue_ge326672fffb7474abfe9baf53b73217e}, \doxyref{keySetBinary()}{p.}{group__keyvalue_ga50a5358fd328d373a45f395fa1b99e7}
 128
 129 \doxyref{keyGetString()}{p.}{group__keyvalue_g41b9fac5ccddafe407fc0ae1e2eb8778} and \doxyref{keySetString()}{p.}{group__keyvalue_g622bde1eb0e0c4994728331326340ef2} as preferred alternative to binary
 130
 131 \doxyref{keyIsBinary()}{p.}{group__keytest_g9526b371087564e43e3dff8ad0dac949} to see how to check for binary type \end{Desc}
 132 \index{keyvalue@{keyvalue}!keyGetComment@{keyGetComment}}
 133 \index{keyGetComment@{keyGetComment}!keyvalue@{keyvalue}}
 134 \subsubsection[keyGetComment]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetComment (const Key $\ast$ {\em key}, \/  char $\ast$ {\em returnedComment}, \/  size\_\-t {\em maxSize})}\label{group__keyvalue_gfb89735689929ff717cc9f2d0d0b46a2}
 135
 136
 137 Get the key comment.\subsection{Comments}\label{group__keyvalue_comment}
 138 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.
 139
 140 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.
 141
 142 \begin{Desc}
 143 \item[Parameters:]
 144 \begin{description}
 145 \item[{\em key}]the key object to work with \item[{\em returnedComment}]pre-allocated memory to copy the comments to \item[{\em maxSize}]number of bytes that will fit returnedComment \end{description}
 146 \end{Desc}
 147 \begin{Desc}
 148 \item[Returns:]the number of bytes actually copied to {\tt returnedString}, including final NULL
 149
 150 1 if the string is empty
 151
 152 -1 on NULL pointer
 153
 154 -1 if maxSize is 0, not enough to store the comment or when larger then SSIZE\_\-MAX \end{Desc}
 155 \begin{Desc}
 156 \item[See also:]\doxyref{keyGetCommentSize()}{p.}{group__keyvalue_g0dd737fadc16d4cf16720d17f066a9d3}, \doxyref{keySetComment()}{p.}{group__keyvalue_g8863a877a84fa46e6017fe72e49b89c1} \end{Desc}
 157 \index{keyvalue@{keyvalue}!keyGetCommentSize@{keyGetCommentSize}}
 158 \index{keyGetCommentSize@{keyGetCommentSize}!keyvalue@{keyvalue}}
 159 \subsubsection[keyGetCommentSize]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetCommentSize (const Key $\ast$ {\em key})}\label{group__keyvalue_g0dd737fadc16d4cf16720d17f066a9d3}
 160
 161
 162 Calculates number of bytes needed to store a key comment, including final NULL.
 163
 164 Use this method to know to size for allocated memory to retrieve a key comment.
 165
 166 See \doxyref{keySetComment()}{p.}{group__keyvalue_g8863a877a84fa46e6017fe72e49b89c1} for more information on comments.
 167
 168 For an empty key name you need one byte to store the ending NULL. For that reason 1 is returned.
 169
 170
 171
 172 \begin{Code}\begin{verbatim}char *buffer;
 173 buffer = malloc (keyGetCommentSize (key));
 174 // use this buffer to store the comment
 175 // pass keyGetCommentSize (key) for maxSize
 176 \end{verbatim}
 177 \end{Code}
 178
 179
 180
 181 \begin{Desc}
 182 \item[Parameters:]
 183 \begin{description}
 184 \item[{\em key}]the key object to work with \end{description}
 185 \end{Desc}
 186 \begin{Desc}
 187 \item[Returns:]number of bytes needed
 188
 189 1 if there is no comment
 190
 191 -1 on NULL pointer \end{Desc}
 192 \begin{Desc}
 193 \item[See also:]\doxyref{keyGetComment()}{p.}{group__keyvalue_gfb89735689929ff717cc9f2d0d0b46a2}, \doxyref{keySetComment()}{p.}{group__keyvalue_g8863a877a84fa46e6017fe72e49b89c1} \end{Desc}
 194 \index{keyvalue@{keyvalue}!keyGetString@{keyGetString}}
 195 \index{keyGetString@{keyGetString}!keyvalue@{keyvalue}}
 196 \subsubsection[keyGetString]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetString (const Key $\ast$ {\em key}, \/  char $\ast$ {\em returnedString}, \/  size\_\-t {\em maxSize})}\label{group__keyvalue_g41b9fac5ccddafe407fc0ae1e2eb8778}
 197
 198
 199 Get the value of a key as a string.
 200
 201 When there is no value inside the string, 1 will be returned and the returnedString will be empty \char`\"{}\char`\"{} to avoid programming errors that old strings are shown to the user.
 202
 203 For binary values see \doxyref{keyGetBinary()}{p.}{group__keyvalue_g4c0d8a4a11174197699c231e0b5c3c84} and \doxyref{keyIsBinary()}{p.}{group__keytest_g9526b371087564e43e3dff8ad0dac949}.
 204
 205 \begin{Desc}
 206 \item[Example:]
 207
 208 \begin{Code}\begin{verbatim}Key *key = keyNew ("user/keyname", KEY_END);
 209 char buffer[300];
 210
 211 if (keyGetString(key,buffer,sizeof(buffer)) == -1)
 212 {
 213         // handle error
 214 } else {
 215         printf ("buffer: %s\n", buffer);
 216 }
 217 \end{verbatim}
 218 \end{Code}
 219
 220 \end{Desc}
 221 \begin{Desc}
 222 \item[Parameters:]
 223 \begin{description}
 224 \item[{\em key}]the object to gather the value from \item[{\em returnedString}]pre-allocated memory to store a copy of the key value \item[{\em maxSize}]number of bytes of allocated memory in {\tt returnedString} \end{description}
 225 \end{Desc}
 226 \begin{Desc}
 227 \item[Returns:]the number of bytes actually copied to {\tt returnedString}, including final NULL
 228
 229 1 if the string is empty
 230
 231 -1 on NULL pointer
 232
 233 -1 on type mismatch
 234
 235 maxSize is 0, too small for string or is larger than SSIZE\_\-MAX \end{Desc}
 236 \begin{Desc}
 237 \item[See also:]\doxyref{keyValue()}{p.}{group__keyvalue_g6f29609c5da53c6dc26a98678d5752af}, \doxyref{keyGetValueSize()}{p.}{group__keyvalue_ge326672fffb7474abfe9baf53b73217e}, \doxyref{keySetString()}{p.}{group__keyvalue_g622bde1eb0e0c4994728331326340ef2}
 238
 239 \doxyref{keyGetBinary()}{p.}{group__keyvalue_g4c0d8a4a11174197699c231e0b5c3c84} for working with binary data \end{Desc}
 240 \index{keyvalue@{keyvalue}!keyGetValueSize@{keyGetValueSize}}
 241 \index{keyGetValueSize@{keyGetValueSize}!keyvalue@{keyvalue}}
 242 \subsubsection[keyGetValueSize]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keyGetValueSize (const Key $\ast$ {\em key})}\label{group__keyvalue_ge326672fffb7474abfe9baf53b73217e}
 243
 244
 245 Returns the number of bytes needed to store the key value, including the NULL terminator.
 246
 247 It returns the correct size, independent of the Key Type. If it is a binary there might be '$\backslash$0' values in it.
 248
 249 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.
 250
 251 A binary key has no '$\backslash$0' termination. String types have it, so to there length will be added 1 to have enough space to store it.
 252
 253 This method can be used with malloc() before \doxyref{keyGetString()}{p.}{group__keyvalue_g41b9fac5ccddafe407fc0ae1e2eb8778} or \doxyref{keyGetBinary()}{p.}{group__keyvalue_g4c0d8a4a11174197699c231e0b5c3c84} is called.
 254
 255
 256
 257 \begin{Code}\begin{verbatim}char *buffer;
 258 buffer = malloc (keyGetValueSize (key));
 259 // use this buffer to store the value (binary or string)
 260 // pass keyGetValueSize (key) for maxSize
 261 \end{verbatim}
 262 \end{Code}
 263
 264
 265
 266 \begin{Desc}
 267 \item[Parameters:]
 268 \begin{description}
 269 \item[{\em key}]the key object to work with \end{description}
 270 \end{Desc}
 271 \begin{Desc}
 272 \item[Returns:]the number of bytes needed to store the key value
 273
 274 1 when there is no data and type is not binary
 275
 276 0 when there is no data and type is binary
 277
 278 -1 on null pointer \end{Desc}
 279 \begin{Desc}
 280 \item[See also:]\doxyref{keyGetString()}{p.}{group__keyvalue_g41b9fac5ccddafe407fc0ae1e2eb8778}, \doxyref{keyGetBinary()}{p.}{group__keyvalue_g4c0d8a4a11174197699c231e0b5c3c84}, \doxyref{keyValue()}{p.}{group__keyvalue_g6f29609c5da53c6dc26a98678d5752af} \end{Desc}
 281 \index{keyvalue@{keyvalue}!keySetBinary@{keySetBinary}}
 282 \index{keySetBinary@{keySetBinary}!keyvalue@{keyvalue}}
 283 \subsubsection[keySetBinary]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keySetBinary (Key $\ast$ {\em key}, \/  const void $\ast$ {\em newBinary}, \/  size\_\-t {\em dataSize})}\label{group__keyvalue_ga50a5358fd328d373a45f395fa1b99e7}
 284
 285
 286 Set the value of a key as a binary.
 287
 288 A private copy of {\tt newBinary} will allocated and saved inside {\tt key}, so the parameter can be deallocated after the call.
 289
 290 The {\tt filesys} backend, when used through a \doxyref{kdbSetKey()}{p.}{group__kdbhighlevel_g23b2f5fead4cddeb5542051a197ddc20}, will make the value be kdbbEncoded into a human readable hex-digit text format.
 291
 292 Consider using a string key instead.
 293
 294 When newBinary is a NULL pointer the binary will be freed and 0 will be returned.
 295
 296 \begin{Desc}
 297 \item[Note:]When the type of the key is already a binary type it won't be changed.\end{Desc}
 298 \begin{Desc}
 299 \item[Parameters:]
 300 \begin{description}
 301 \item[{\em key}]the object on which to set the value \item[{\em newBinary}]is a pointer to any binary data or NULL to free the previous set data \item[{\em dataSize}]number of bytes to copy from {\tt newBinary} \end{description}
 302 \end{Desc}
 303 \begin{Desc}
 304 \item[Returns:]the number of bytes actually copied to internal struct storage
 305
 306 0 when the internal binary was freed
 307
 308 -1 on NULL pointer
 309
 310 -1 when dataSize is 0 (but newBinary not NULL) or larger than SSIZE\_\-MAX \end{Desc}
 311 \begin{Desc}
 312 \item[See also:]\doxyref{keyGetBinary()}{p.}{group__keyvalue_g4c0d8a4a11174197699c231e0b5c3c84}
 313
 314 \doxyref{keyIsBinary()}{p.}{group__keytest_g9526b371087564e43e3dff8ad0dac949} to check if the type is binary
 315
 316 \doxyref{keyGetString()}{p.}{group__keyvalue_g41b9fac5ccddafe407fc0ae1e2eb8778} and \doxyref{keySetString()}{p.}{group__keyvalue_g622bde1eb0e0c4994728331326340ef2} as preferred alternative to binary \end{Desc}
 317 \index{keyvalue@{keyvalue}!keySetComment@{keySetComment}}
 318 \index{keySetComment@{keySetComment}!keyvalue@{keyvalue}}
 319 \subsubsection[keySetComment]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keySetComment (Key $\ast$ {\em key}, \/  const char $\ast$ {\em newComment})}\label{group__keyvalue_g8863a877a84fa46e6017fe72e49b89c1}
 320
 321
 322 Set a comment for a key.
 323
 324 A key comment is like a configuration file comment. See \doxyref{keySetComment()}{p.}{group__keyvalue_g8863a877a84fa46e6017fe72e49b89c1} for more information.
 325
 326 \begin{Desc}
 327 \item[Parameters:]
 328 \begin{description}
 329 \item[{\em key}]the key object to work with \item[{\em newComment}]the comment, that can be freed after this call. \end{description}
 330 \end{Desc}
 331 \begin{Desc}
 332 \item[Returns:]the number of bytes actually saved including final NULL
 333
 334 1 when the comment was freed
 335
 336 -1 on NULL pointer or memory problems \end{Desc}
 337 \begin{Desc}
 338 \item[See also:]\doxyref{keyGetComment()}{p.}{group__keyvalue_gfb89735689929ff717cc9f2d0d0b46a2} \end{Desc}
 339 \index{keyvalue@{keyvalue}!keySetString@{keySetString}}
 340 \index{keySetString@{keySetString}!keyvalue@{keyvalue}}
 341 \subsubsection[keySetString]{\setlength{\rightskip}{0pt plus 5cm}ssize\_\-t keySetString (Key $\ast$ {\em key}, \/  const char $\ast$ {\em newStringValue})}\label{group__keyvalue_g622bde1eb0e0c4994728331326340ef2}
 342
 343
 344 Set the value for {\tt key} as {\tt newStringValue}.
 345
 346 The function will allocate and save a private copy of {\tt newStringValue}, so the parameter can be freed after the call.
 347
 348 String values will be saved in backend storage, when \doxyref{kdbSetKey()}{p.}{group__kdbhighlevel_g23b2f5fead4cddeb5542051a197ddc20} will be called, in UTF-8 universal encoding, regardless of the program's current encoding, when compiled with --enable-iconv.
 349
 350 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.
 351
 352 \begin{Desc}
 353 \item[Parameters:]
 354 \begin{description}
 355 \item[{\em key}]the key to set the string value \item[{\em newStringValue}]NULL-terminated text string to be set as {\tt key's} value \end{description}
 356 \end{Desc}
 357 \begin{Desc}
 358 \item[Returns:]the number of bytes actually saved in private struct including final NULL
 359
 360 -1 on NULL pointer \end{Desc}
 361 \begin{Desc}
 362 \item[See also:]\doxyref{keyGetString()}{p.}{group__keyvalue_g41b9fac5ccddafe407fc0ae1e2eb8778}, \doxyref{keyValue()}{p.}{group__keyvalue_g6f29609c5da53c6dc26a98678d5752af} \end{Desc}
 363 \index{keyvalue@{keyvalue}!keyValue@{keyValue}}
 364 \index{keyValue@{keyValue}!keyvalue@{keyvalue}}
 365 \subsubsection[keyValue]{\setlength{\rightskip}{0pt plus 5cm}const void$\ast$ keyValue (const Key $\ast$ {\em key})}\label{group__keyvalue_g6f29609c5da53c6dc26a98678d5752af}
 366
 367
 368 Return a pointer to the real internal {\tt key} value.
 369
 370 This is a much more efficient version of \doxyref{keyGetString()}{p.}{group__keyvalue_g41b9fac5ccddafe407fc0ae1e2eb8778} \doxyref{keyGetBinary()}{p.}{group__keyvalue_g4c0d8a4a11174197699c231e0b5c3c84}, 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 \doxyref{keyGetString()}{p.}{group__keyvalue_g41b9fac5ccddafe407fc0ae1e2eb8778} or \doxyref{keyGetBinary()}{p.}{group__keyvalue_g4c0d8a4a11174197699c231e0b5c3c84} instead.\subsection{String Handling}\label{group__keyvalue_string}
 371 If {\tt key} is string (\doxyref{keyIsString()}{p.}{group__keytest_gea7670778abd07fee0fe8ac12a149190}), you may cast the returned as a {\tt \char`\"{}char $\ast$\char`\"{}} because you'll get a NULL terminated regular string.
 372
 373 \doxyref{keyValue()}{p.}{group__keyvalue_g6f29609c5da53c6dc26a98678d5752af} returns \char`\"{}\char`\"{} in string mode when there is no value. The reason is
 374
 375 \begin{Code}\begin{verbatim}key=keyNew(0);
 376 keySetString(key,"");
 377 keyValue(key); // you would expect "" here
 378 keyDel(key);
 379 \end{verbatim}
 380 \end{Code}
 381
 382 \subsection{Binary Data Handling}\label{group__keyvalue_binary}
 383 If the data is binary, the size of the value must be determined by \doxyref{keyGetValueSize()}{p.}{group__keyvalue_ge326672fffb7474abfe9baf53b73217e}, any strlen() operations are not suitable to determine the size.
 384
 385 \doxyref{keyValue()}{p.}{group__keyvalue_g6f29609c5da53c6dc26a98678d5752af} returns 0 in binary mode when there is no value. The reason is
 386
 387 \begin{Code}\begin{verbatim}int i=23;
 388 key=keyNew(0);
 389 keySetBinary(key, 0, 0);
 390 keyValue(key); // you would expect 0 here
 391
 392 keySetBinary(key,"", 1);
 393 keyValue(key); // you would expect "" (a pointer to '\0') here
 394
 395 keySetBinary(key, (void*)&i, 4);
 396 (int*)keyValue(key); // you would expect a pointer to (int)23 here
 397 keyDel(key);
 398 \end{verbatim}
 399 \end{Code}
 400
 401
 402
 403 \begin{Desc}
 404 \item[Note:]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 \doxyref{keyValue()}{p.}{group__keyvalue_g6f29609c5da53c6dc26a98678d5752af} method to set a new value. Use \doxyref{keySetString()}{p.}{group__keyvalue_g622bde1eb0e0c4994728331326340ef2} or \doxyref{keySetBinary()}{p.}{group__keyvalue_ga50a5358fd328d373a45f395fa1b99e7} instead.\end{Desc}
 405 \begin{Desc}
 406 \item[Warning:]Binary keys will return a NULL pointer when there is no data in contrast to \doxyref{keyName()}{p.}{group__keyname_g8e805c726a60da921d3736cda7813513}, \doxyref{keyBaseName()}{p.}{group__keyname_gaff35e7ca8af5560c47e662ceb9465f5}, \doxyref{keyOwner()}{p.}{group__keyname_gf6485fb8599714b6bbd830cf915ffea5} and \doxyref{keyComment()}{p.}{group__keyvalue_gc89fd319783b3457db45b4c09e55274a}. For string value the behaviour is the same.\end{Desc}
 407 \begin{Desc}
 408 \item[Example:]
 409
 410 \begin{Code}\begin{verbatim}KDB *handle = kdbOpen();
 411 KeySet *ks=ksNew(0);
 412 Key *current=0;
 413
 414 kdbGetByName(handle,ks,"system/sw/my",KDB_O_SORT|KDB_O_RECURSIVE);
 415
 416 ksRewind(ks);
 417 while(current=ksNext(ks)) {
 418         size_t size=0;
 419
 420         if (keyIsBin(current)) {
 421                 size=keyGetValueSize(current);
 422                 printf("Key %s has a value of size %d bytes. Value: <BINARY>\nComment: %s",
 423                         keyName(current),
 424                         size,
 425                         keyComment(current));
 426         } else {
 427                 size=kdbiStrLen((char *)keyValue(current));
 428                 printf("Key %s has a value of size %d bytes. Value: %s\nComment: %s",
 429                         keyName(current),
 430                         size,
 431                         (char *)keyValue(current),
 432                         keyComment(current));
 433         }
 434 }
 435
 436 ksDel (ks);
 437 kdbClose (handle);
 438 \end{verbatim}
 439 \end{Code}
 440
 441 \end{Desc}
 442 \begin{Desc}
 443 \item[Parameters:]
 444 \begin{description}
 445 \item[{\em key}]the key object to work with \end{description}
 446 \end{Desc}
 447 \begin{Desc}
 448 \item[Returns:]a pointer to internal value
 449
 450 \char`\"{}\char`\"{} when there is no data and key is not binary
 451
 452 0 where there is no data and key is binary
 453
 454 0 on NULL pointer \end{Desc}
 455 \begin{Desc}
 456 \item[See also:]\doxyref{keyGetValueSize()}{p.}{group__keyvalue_ge326672fffb7474abfe9baf53b73217e}, \doxyref{keyGetString()}{p.}{group__keyvalue_g41b9fac5ccddafe407fc0ae1e2eb8778}, \doxyref{keyGetBinary()}{p.}{group__keyvalue_g4c0d8a4a11174197699c231e0b5c3c84} \end{Desc}