doc/elektra-api/man/man3/keyvalue.3

   1 .TH "Key :: Value Manipulation Methods" 3 "30 Jun 2009" "Elektra Projekt" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 Key :: Value Manipulation Methods \- Methods to do various operations on Key values.
   6
   7 .PP
   8 .SS "Functions"
   9
  10 .in +1c
  11 .ti -1c
  12 .RI "const void * \fBkeyValue\fP (const Key *key)"
  13 .br
  14 .ti -1c
  15 .RI "ssize_t \fBkeyGetValueSize\fP (const Key *key)"
  16 .br
  17 .ti -1c
  18 .RI "ssize_t \fBkeyGetString\fP (const Key *key, char *returnedString, size_t maxSize)"
  19 .br
  20 .ti -1c
  21 .RI "ssize_t \fBkeySetString\fP (Key *key, const char *newStringValue)"
  22 .br
  23 .ti -1c
  24 .RI "ssize_t \fBkeyGetBinary\fP (const Key *key, void *returnedBinary, size_t maxSize)"
  25 .br
  26 .ti -1c
  27 .RI "ssize_t \fBkeySetBinary\fP (Key *key, const void *newBinary, size_t dataSize)"
  28 .br
  29 .ti -1c
  30 .RI "const char * \fBkeyComment\fP (const Key *key)"
  31 .br
  32 .ti -1c
  33 .RI "ssize_t \fBkeyGetCommentSize\fP (const Key *key)"
  34 .br
  35 .ti -1c
  36 .RI "ssize_t \fBkeyGetComment\fP (const Key *key, char *returnedComment, size_t maxSize)"
  37 .br
  38 .ti -1c
  39 .RI "ssize_t \fBkeySetComment\fP (Key *key, const char *newComment)"
  40 .br
  41 .in -1c
  42 .SH "Detailed Description"
  43 .PP
  44 Methods to do various operations on Key values.
  45 .PP
  46 A key can contain a value in different format. The most likely situation is, that the value is interpreted as text. Use \fBkeyGetString()\fP for that. You can save any Unicode Symbols and Elektra will take care that you get the same back, independent of your current environment.
  47 .PP
  48 In some situations this idea fails. When you need exactly the same value back without any interpretation of the characters, there is \fBkeySetBinary()\fP. 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 \fBkeyGetString()\fP. To do so, you might use strtod() strtol() and then atol() or atof() to convert back.
  49 .PP
  50 To use them:
  51 .PP
  52 .nf
  53 #include <kdb.h>
  54
  55 .fi
  56 .PP
  57
  58 .SH "Function Documentation"
  59 .PP
  60 .SS "const char* keyComment (const Key * key)"
  61 .PP
  62 Return a pointer to the real internal \fCkey\fP comment.
  63 .PP
  64 This is a much more efficient version of \fBkeyGetComment()\fP 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.
  65 .PP
  66 \fBkeyComment()\fP returns '' when there is no keyComment. The reason is
  67 .PP
  68 .nf
  69 key=keyNew(0);
  70 keySetComment(key,'');
  71 keyComment(key); // you would expect '' here
  72 keyDel(key);
  73
  74 .fi
  75 .PP
  76 .PP
  77 See \fBkeySetComment()\fP for more information on comments.
  78 .PP
  79 \fBNote:\fP
  80 .RS 4
  81 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 \fBkeyComment()\fP method to set a new value. Use \fBkeySetComment()\fP instead.
  82 .RE
  83 .PP
  84 \fBParameters:\fP
  85 .RS 4
  86 \fIkey\fP the key object to work with
  87 .RE
  88 .PP
  89 \fBReturns:\fP
  90 .RS 4
  91 a pointer to the internal managed comment
  92 .PP
  93 '' when there is no comment
  94 .PP
  95 0 on NULL pointer
  96 .RE
  97 .PP
  98 \fBSee also:\fP
  99 .RS 4
 100 \fBkeyGetCommentSize()\fP for size and \fBkeyGetComment()\fP as alternative
 101 .RE
 102 .PP
 103
 104 .SS "ssize_t keyGetBinary (const Key * key, void * returnedBinary, size_t maxSize)"
 105 .PP
 106 Get the value of a key as a binary.
 107 .PP
 108 If the type is not binary -1 will be returned.
 109 .PP
 110 When the binary data is empty (this is not the same as ''!) 0 will be returned and the returnedBinary will not be changed.
 111 .PP
 112 For string values see \fBkeyGetString()\fP and \fBkeyIsString()\fP.
 113 .PP
 114 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.
 115 .PP
 116 \fBExample:\fP.RS 4
 117
 118 .PP
 119 .nf
 120 Key *key = keyNew ('user/keyname', KEY_TYPE, KEY_TYPE_BINARY, KEY_END);
 121 char buffer[300];
 122
 123 if (keyGetBinary(key,buffer,sizeof(buffer)) == -1)
 124 {
 125         // handle error
 126 }
 127
 128 .fi
 129 .PP
 130 .RE
 131 .PP
 132 \fBParameters:\fP
 133 .RS 4
 134 \fIkey\fP the object to gather the value from
 135 .br
 136 \fIreturnedBinary\fP pre-allocated memory to store a copy of the key value
 137 .br
 138 \fImaxSize\fP number of bytes of pre-allocated memory in \fCreturnedBinary\fP
 139 .RE
 140 .PP
 141 \fBReturns:\fP
 142 .RS 4
 143 the number of bytes actually copied to \fCreturnedBinary\fP
 144 .PP
 145 0 if the binary is empty
 146 .PP
 147 -1 on NULL pointers
 148 .PP
 149 -1 when maxSize is 0, too small to hold the value or larger than SSIZE_MAX
 150 .PP
 151 -1 on typing error when the key is not binary
 152 .RE
 153 .PP
 154 \fBSee also:\fP
 155 .RS 4
 156 \fBkeyValue()\fP, \fBkeyGetValueSize()\fP, \fBkeySetBinary()\fP
 157 .PP
 158 \fBkeyGetString()\fP and \fBkeySetString()\fP as preferred alternative to binary
 159 .PP
 160 \fBkeyIsBinary()\fP to see how to check for binary type
 161 .RE
 162 .PP
 163
 164 .SS "ssize_t keyGetComment (const Key * key, char * returnedComment, size_t maxSize)"
 165 .PP
 166 Get the key comment.
 167 .SH "Comments"
 168 .PP
 169 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.
 170 .PP
 171 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.
 172 .PP
 173 \fBParameters:\fP
 174 .RS 4
 175 \fIkey\fP the key object to work with
 176 .br
 177 \fIreturnedComment\fP pre-allocated memory to copy the comments to
 178 .br
 179 \fImaxSize\fP number of bytes that will fit returnedComment
 180 .RE
 181 .PP
 182 \fBReturns:\fP
 183 .RS 4
 184 the number of bytes actually copied to \fCreturnedString\fP, including final NULL
 185 .PP
 186 1 if the string is empty
 187 .PP
 188 -1 on NULL pointer
 189 .PP
 190 -1 if maxSize is 0, not enough to store the comment or when larger then SSIZE_MAX
 191 .RE
 192 .PP
 193 \fBSee also:\fP
 194 .RS 4
 195 \fBkeyGetCommentSize()\fP, \fBkeySetComment()\fP
 196 .RE
 197 .PP
 198
 199 .SS "ssize_t keyGetCommentSize (const Key * key)"
 200 .PP
 201 Calculates number of bytes needed to store a key comment, including final NULL.
 202 .PP
 203 Use this method to know to size for allocated memory to retrieve a key comment.
 204 .PP
 205 See \fBkeySetComment()\fP for more information on comments.
 206 .PP
 207 For an empty key name you need one byte to store the ending NULL. For that reason 1 is returned.
 208 .PP
 209 .PP
 210 .nf
 211 char *buffer;
 212 buffer = malloc (keyGetCommentSize (key));
 213 // use this buffer to store the comment
 214 // pass keyGetCommentSize (key) for maxSize
 215 .fi
 216 .PP
 217 .PP
 218 \fBParameters:\fP
 219 .RS 4
 220 \fIkey\fP the key object to work with
 221 .RE
 222 .PP
 223 \fBReturns:\fP
 224 .RS 4
 225 number of bytes needed
 226 .PP
 227 1 if there is no comment
 228 .PP
 229 -1 on NULL pointer
 230 .RE
 231 .PP
 232 \fBSee also:\fP
 233 .RS 4
 234 \fBkeyGetComment()\fP, \fBkeySetComment()\fP
 235 .RE
 236 .PP
 237
 238 .SS "ssize_t keyGetString (const Key * key, char * returnedString, size_t maxSize)"
 239 .PP
 240 Get the value of a key as a string.
 241 .PP
 242 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.
 243 .PP
 244 For binary values see \fBkeyGetBinary()\fP and \fBkeyIsBinary()\fP.
 245 .PP
 246 \fBExample:\fP.RS 4
 247
 248 .PP
 249 .nf
 250 Key *key = keyNew ('user/keyname', KEY_END);
 251 char buffer[300];
 252
 253 if (keyGetString(key,buffer,sizeof(buffer)) == -1)
 254 {
 255         // handle error
 256 } else {
 257         printf ('buffer: %s\n', buffer);
 258 }
 259
 260 .fi
 261 .PP
 262 .RE
 263 .PP
 264 \fBParameters:\fP
 265 .RS 4
 266 \fIkey\fP the object to gather the value from
 267 .br
 268 \fIreturnedString\fP pre-allocated memory to store a copy of the key value
 269 .br
 270 \fImaxSize\fP number of bytes of allocated memory in \fCreturnedString\fP
 271 .RE
 272 .PP
 273 \fBReturns:\fP
 274 .RS 4
 275 the number of bytes actually copied to \fCreturnedString\fP, including final NULL
 276 .PP
 277 1 if the string is empty
 278 .PP
 279 -1 on NULL pointer
 280 .PP
 281 -1 on type mismatch
 282 .PP
 283 maxSize is 0, too small for string or is larger than SSIZE_MAX
 284 .RE
 285 .PP
 286 \fBSee also:\fP
 287 .RS 4
 288 \fBkeyValue()\fP, \fBkeyGetValueSize()\fP, \fBkeySetString()\fP
 289 .PP
 290 \fBkeyGetBinary()\fP for working with binary data
 291 .RE
 292 .PP
 293
 294 .SS "ssize_t keyGetValueSize (const Key * key)"
 295 .PP
 296 Returns the number of bytes needed to store the key value, including the NULL terminator.
 297 .PP
 298 It returns the correct size, independent of the Key Type. If it is a binary there might be '\\0' values in it.
 299 .PP
 300 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.
 301 .PP
 302 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.
 303 .PP
 304 This method can be used with malloc() before \fBkeyGetString()\fP or \fBkeyGetBinary()\fP is called.
 305 .PP
 306 .PP
 307 .nf
 308 char *buffer;
 309 buffer = malloc (keyGetValueSize (key));
 310 // use this buffer to store the value (binary or string)
 311 // pass keyGetValueSize (key) for maxSize
 312 .fi
 313 .PP
 314 .PP
 315 \fBParameters:\fP
 316 .RS 4
 317 \fIkey\fP the key object to work with
 318 .RE
 319 .PP
 320 \fBReturns:\fP
 321 .RS 4
 322 the number of bytes needed to store the key value
 323 .PP
 324 1 when there is no data and type is not binary
 325 .PP
 326 0 when there is no data and type is binary
 327 .PP
 328 -1 on null pointer
 329 .RE
 330 .PP
 331 \fBSee also:\fP
 332 .RS 4
 333 \fBkeyGetString()\fP, \fBkeyGetBinary()\fP, \fBkeyValue()\fP
 334 .RE
 335 .PP
 336
 337 .SS "ssize_t keySetBinary (Key * key, const void * newBinary, size_t dataSize)"
 338 .PP
 339 Set the value of a key as a binary.
 340 .PP
 341 A private copy of \fCnewBinary\fP will allocated and saved inside \fCkey\fP, so the parameter can be deallocated after the call.
 342 .PP
 343 The \fCfilesys\fP backend, when used through a \fBkdbSetKey()\fP, will make the value be kdbbEncoded into a human readable hex-digit text format.
 344 .PP
 345 Consider using a string key instead.
 346 .PP
 347 When newBinary is a NULL pointer the binary will be freed and 0 will be returned.
 348 .PP
 349 \fBNote:\fP
 350 .RS 4
 351 When the type of the key is already a binary type it won't be changed.
 352 .RE
 353 .PP
 354 \fBParameters:\fP
 355 .RS 4
 356 \fIkey\fP the object on which to set the value
 357 .br
 358 \fInewBinary\fP is a pointer to any binary data or NULL to free the previous set data
 359 .br
 360 \fIdataSize\fP number of bytes to copy from \fCnewBinary\fP
 361 .RE
 362 .PP
 363 \fBReturns:\fP
 364 .RS 4
 365 the number of bytes actually copied to internal struct storage
 366 .PP
 367 0 when the internal binary was freed
 368 .PP
 369 -1 on NULL pointer
 370 .PP
 371 -1 when dataSize is 0 (but newBinary not NULL) or larger than SSIZE_MAX
 372 .RE
 373 .PP
 374 \fBSee also:\fP
 375 .RS 4
 376 \fBkeyGetBinary()\fP
 377 .PP
 378 \fBkeyIsBinary()\fP to check if the type is binary
 379 .PP
 380 \fBkeyGetString()\fP and \fBkeySetString()\fP as preferred alternative to binary
 381 .RE
 382 .PP
 383
 384 .SS "ssize_t keySetComment (Key * key, const char * newComment)"
 385 .PP
 386 Set a comment for a key.
 387 .PP
 388 A key comment is like a configuration file comment. See \fBkeySetComment()\fP for more information.
 389 .PP
 390 \fBParameters:\fP
 391 .RS 4
 392 \fIkey\fP the key object to work with
 393 .br
 394 \fInewComment\fP the comment, that can be freed after this call.
 395 .RE
 396 .PP
 397 \fBReturns:\fP
 398 .RS 4
 399 the number of bytes actually saved including final NULL
 400 .PP
 401 1 when the comment was freed
 402 .PP
 403 -1 on NULL pointer or memory problems
 404 .RE
 405 .PP
 406 \fBSee also:\fP
 407 .RS 4
 408 \fBkeyGetComment()\fP
 409 .RE
 410 .PP
 411
 412 .SS "ssize_t keySetString (Key * key, const char * newStringValue)"
 413 .PP
 414 Set the value for \fCkey\fP as \fCnewStringValue\fP.
 415 .PP
 416 The function will allocate and save a private copy of \fCnewStringValue\fP, so the parameter can be freed after the call.
 417 .PP
 418 String values will be saved in backend storage, when \fBkdbSetKey()\fP will be called, in UTF-8 universal encoding, regardless of the program's current encoding, when compiled with --enable-iconv.
 419 .PP
 420 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.
 421 .PP
 422 \fBParameters:\fP
 423 .RS 4
 424 \fIkey\fP the key to set the string value
 425 .br
 426 \fInewStringValue\fP NULL-terminated text string to be set as \fCkey's\fP value
 427 .RE
 428 .PP
 429 \fBReturns:\fP
 430 .RS 4
 431 the number of bytes actually saved in private struct including final NULL
 432 .PP
 433 -1 on NULL pointer
 434 .RE
 435 .PP
 436 \fBSee also:\fP
 437 .RS 4
 438 \fBkeyGetString()\fP, \fBkeyValue()\fP
 439 .RE
 440 .PP
 441
 442 .SS "const void* keyValue (const Key * key)"
 443 .PP
 444 Return a pointer to the real internal \fCkey\fP value.
 445 .PP
 446 This is a much more efficient version of \fBkeyGetString()\fP \fBkeyGetBinary()\fP, 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 \fBkeyGetString()\fP or \fBkeyGetBinary()\fP instead.
 447 .SH "String Handling"
 448 .PP
 449 If \fCkey\fP is string (\fBkeyIsString()\fP), you may cast the returned as a \fC'char *'\fP because you'll get a NULL terminated regular string.
 450 .PP
 451 \fBkeyValue()\fP returns '' in string mode when there is no value. The reason is
 452 .PP
 453 .nf
 454 key=keyNew(0);
 455 keySetString(key,'');
 456 keyValue(key); // you would expect '' here
 457 keyDel(key);
 458
 459 .fi
 460 .PP
 461 .SH "Binary Data Handling"
 462 .PP
 463 If the data is binary, the size of the value must be determined by \fBkeyGetValueSize()\fP, any strlen() operations are not suitable to determine the size.
 464 .PP
 465 \fBkeyValue()\fP returns 0 in binary mode when there is no value. The reason is
 466 .PP
 467 .nf
 468 int i=23;
 469 key=keyNew(0);
 470 keySetBinary(key, 0, 0);
 471 keyValue(key); // you would expect 0 here
 472
 473 keySetBinary(key,'', 1);
 474 keyValue(key); // you would expect '' (a pointer to '\0') here
 475
 476 keySetBinary(key, (void*)&i, 4);
 477 (int*)keyValue(key); // you would expect a pointer to (int)23 here
 478 keyDel(key);
 479
 480 .fi
 481 .PP
 482 .PP
 483 \fBNote:\fP
 484 .RS 4
 485 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 \fBkeyValue()\fP method to set a new value. Use \fBkeySetString()\fP or \fBkeySetBinary()\fP instead.
 486 .RE
 487 .PP
 488 \fBWarning:\fP
 489 .RS 4
 490 Binary keys will return a NULL pointer when there is no data in contrast to \fBkeyName()\fP, \fBkeyBaseName()\fP, \fBkeyOwner()\fP and \fBkeyComment()\fP. For string value the behaviour is the same.
 491 .RE
 492 .PP
 493 \fBExample:\fP.RS 4
 494
 495 .PP
 496 .nf
 497 KDB *handle = kdbOpen();
 498 KeySet *ks=ksNew(0);
 499 Key *current=0;
 500
 501 kdbGetByName(handle,ks,'system/sw/my',KDB_O_SORT|KDB_O_RECURSIVE);
 502
 503 ksRewind(ks);
 504 while(current=ksNext(ks)) {
 505         size_t size=0;
 506
 507         if (keyIsBin(current)) {
 508                 size=keyGetValueSize(current);
 509                 printf('Key %s has a value of size %d bytes. Value: <BINARY>\nComment: %s',
 510                         keyName(current),
 511                         size,
 512                         keyComment(current));
 513         } else {
 514                 size=kdbiStrLen((char *)keyValue(current));
 515                 printf('Key %s has a value of size %d bytes. Value: %s\nComment: %s',
 516                         keyName(current),
 517                         size,
 518                         (char *)keyValue(current),
 519                         keyComment(current));
 520         }
 521 }
 522
 523 ksDel (ks);
 524 kdbClose (handle);
 525
 526 .fi
 527 .PP
 528 .RE
 529 .PP
 530 \fBParameters:\fP
 531 .RS 4
 532 \fIkey\fP the key object to work with
 533 .RE
 534 .PP
 535 \fBReturns:\fP
 536 .RS 4
 537 a pointer to internal value
 538 .PP
 539 '' when there is no data and key is not binary
 540 .PP
 541 0 where there is no data and key is binary
 542 .PP
 543 0 on NULL pointer
 544 .RE
 545 .PP
 546 \fBSee also:\fP
 547 .RS 4
 548 \fBkeyGetValueSize()\fP, \fBkeyGetString()\fP, \fBkeyGetBinary()\fP
 549 .RE
 550 .PP
 551