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

   1 .TH "Streaming" 3 "30 Jun 2009" "Elektra Projekt" \" -*- nroff -*-
   2 .ad l
   3 .nh
   4 .SH NAME
   5 Streaming \- Methods to output, generate and toXML Keys and Keysets.
   6
   7 .PP
   8 .SS "Enumerations"
   9
  10 .in +1c
  11 .ti -1c
  12 .RI "enum \fBKDBStream\fP { \fBKDB_O_SHOWMETA\fP = 0xF0, \fBKDB_O_SHOWFLAGS\fP = 1<<14, \fBKDB_O_SHOWINDICES\fP = 1<<15, \fBKDB_O_CONDENSED\fP = 1<<16, \fBKDB_O_NUMBER\fP = 1<<17, \fBKDB_O_HEADER\fP = 1<<18, \fBKDB_O_FULLNAME\fP = 1<<19, \fBKDB_O_HIER\fP = 1<<20 }"
  13 .br
  14 .in -1c
  15 .SS "Functions"
  16
  17 .in +1c
  18 .ti -1c
  19 .RI "int \fBksFromXMLfile\fP (KeySet *ks, const char *filename)"
  20 .br
  21 .ti -1c
  22 .RI "int \fBksFromXML\fP (KeySet *ks, int fd)"
  23 .br
  24 .ti -1c
  25 .RI "ssize_t \fBkeyToStream\fP (const Key *key, FILE *stream, option_t options)"
  26 .br
  27 .ti -1c
  28 .RI "ssize_t \fBkeyToStreamBasename\fP (const Key *key, FILE *stream, const char *parent, const size_t parentSize, option_t options)"
  29 .br
  30 .ti -1c
  31 .RI "ssize_t \fBksToStream\fP (const KeySet *ks, FILE *stream, option_t options)"
  32 .br
  33 .ti -1c
  34 .RI "int \fBkeyOutput\fP (const Key *k, FILE *stream, option_t options)"
  35 .br
  36 .ti -1c
  37 .RI "int \fBksOutput\fP (const KeySet *ks, FILE *stream, option_t options)"
  38 .br
  39 .ti -1c
  40 .RI "int \fBkeyGenerate\fP (const Key *key, FILE *stream, option_t options)"
  41 .br
  42 .ti -1c
  43 .RI "int \fBksGenerate\fP (const KeySet *ks, FILE *stream, option_t options)"
  44 .br
  45 .in -1c
  46 .SH "Detailed Description"
  47 .PP
  48 Methods to output, generate and toXML Keys and Keysets.
  49 .PP
  50 Here are some functions that are in a separate library because they depend on non-basic libraries as libxml. Link against kdbtools library if your program won't be installed in /bin, or is not essential in early boot stages.
  51 .PP
  52 It is also possible to have a dynamic linkage, see the sourcecode from kdb-tool or testing framework how to achieve that.
  53 .PP
  54 Output prints keys line per line, meaned to be read by humans.
  55 .IP "\(bu" 2
  56 \fBkeyOutput()\fP
  57 .IP "\(bu" 2
  58 \fBksOutput()\fP
  59 .PP
  60 .PP
  61 Generate prints keys and keysets as C-Structs, meaned to be read by a C-Compiler.
  62 .IP "\(bu" 2
  63 \fBkeyGenerate()\fP
  64 .IP "\(bu" 2
  65 \fBksGenerate()\fP
  66 .PP
  67 .PP
  68 toXML prints keys and keysets as XML, meaned to be used as exchange format.
  69 .IP "\(bu" 2
  70 \fBkeyToStream()\fP
  71 .IP "\(bu" 2
  72 \fBksToStream()\fP
  73 .PP
  74 .PP
  75 To use them:
  76 .PP
  77 .nf
  78 #include <kdbtools.h>
  79
  80 .fi
  81 .PP
  82
  83 .SH "Enumeration Type Documentation"
  84 .PP
  85 .SS "enum \fBKDBStream\fP"
  86 .PP
  87 Options to change the default behavior of streaming.
  88 .PP
  89 On default the streaming options only output the names of the given keysets. If you want more information, header, metainfo, compressed output, full names, values or comments you will find the appropriate options here.
  90 .PP
  91 For full influence of value, comment and metadata shown, use these options together with keyswitch_t. All bits of meta-information ORed together are KDB_O_SHOWMETA.
  92 .PP
  93 For more information about the flags, consult the documentation of the streaming methods.
  94 .PP
  95 These options can be ORed. That is the |-Operator in C.
  96 .PP
  97 It uses the values defined in keyswitch_t too, so it starts with 14.
  98 .PP
  99 \fBSee also:\fP
 100 .RS 4
 101 kdbGetChildKeys()
 102 .PP
 103 \fBksToStream()\fP
 104 .PP
 105 \fBkeyToStream()\fP
 106 .RE
 107 .PP
 108
 109 .PP
 110 \fBEnumerator: \fP
 111 .in +1c
 112 .TP
 113 \fB\fIKDB_O_SHOWMETA \fP\fP
 114 Show all metadata (type, uid, gid, mode)
 115 .TP
 116 \fB\fIKDB_O_SHOWFLAGS \fP\fP
 117 Show all flags
 118 .TP
 119 \fB\fIKDB_O_SHOWINDICES \fP\fP
 120 Show the indices for the entries
 121 .TP
 122 \fB\fIKDB_O_CONDENSED \fP\fP
 123 Spare any whitespaces and do not group visually together.
 124 .TP
 125 \fB\fIKDB_O_NUMBER \fP\fP
 126 Use a number intead of user and group name.
 127 .TP
 128 \fB\fIKDB_O_HEADER \fP\fP
 129 Show also the header of the document.
 130 .TP
 131 \fB\fIKDB_O_FULLNAME \fP\fP
 132 Export \fCuser\fP keys using full name.
 133 .TP
 134 \fB\fIKDB_O_HIER \fP\fP
 135 Export to the new hierarchical XML representation using key basename. See \fBksToStream()\fP.
 136 .SH "Function Documentation"
 137 .PP
 138 .SS "int keyGenerate (const Key * key, FILE * stream, option_t options)"
 139 .PP
 140 Generate a C-Style key and stream it.
 141 .PP
 142 This keyset can be used to include as c-code for applikations using elektra.
 143 .PP
 144 \fBParameters:\fP
 145 .RS 4
 146 \fIkey\fP the key object to work with
 147 .br
 148 \fIstream\fP the file pointer where to send the stream
 149 .br
 150 \fIoptions\fP KDB_O_SHOWINDICES, KDB_O_IGNORE_COMMENT, KDB_O_SHOWINFO
 151 .RE
 152 .PP
 153 \fBReturns:\fP
 154 .RS 4
 155 1 on success
 156 .RE
 157 .PP
 158
 159 .SS "int keyOutput (const Key * k, FILE * stream, option_t options)"
 160 .PP
 161 Output every information of a single key depending on options.
 162 .PP
 163 The format is not very strict and only intend to be read by human eyes for debugging purposes. Don't rely on the format in your applications.
 164 .PP
 165 \fBParameters:\fP
 166 .RS 4
 167 \fIk\fP the key object to work with
 168 .br
 169 \fIstream\fP the file pointer where to send the stream
 170 .br
 171 \fIoptions\fP see text above
 172 .RE
 173 .PP
 174 \fBSee also:\fP
 175 .RS 4
 176 \fBksOutput()\fP
 177 .RE
 178 .PP
 179 \fBReturns:\fP
 180 .RS 4
 181 1 on success
 182 .PP
 183 -1 on allocation errors
 184 .RE
 185 .PP
 186
 187 .SS "ssize_t keyToStream (const Key * key, FILE * stream, option_t options)"
 188 .PP
 189 Prints an XML representation of the key.
 190 .PP
 191 String generated is of the form:
 192 .PP
 193 .nf
 194
 195         <key name="system/sw/xorg/Monitor/Monitor0/Name"
 196                 type="string" uid="root" gid="root" mode="0660">
 197
 198                 <value>Samsung TFT panel</value>
 199                 <comment>My monitor</comment>
 200         </key>
 201 .fi
 202 .PP
 203 .PP
 204 .PP
 205 .nf
 206
 207         <key parent="system/sw/xorg/Monitor/Monitor0" basename="Name"
 208                 type="string" uid="root" gid="root" mode="0660">
 209
 210                 <value>Samsung TFT panel</value>
 211                 <comment>My monitor</comment>
 212         </key>.fi
 213 .PP
 214 .PP
 215 \fBParameters:\fP
 216 .RS 4
 217 \fIkey\fP the key object to work with
 218 .br
 219 \fIstream\fP where to write output: a file or stdout
 220 .br
 221 \fIoptions\fP Some option_t ORed:
 222 .IP "\(bu" 2
 223 \fCoption_t::KDB_O_NUMBERS\fP
 224 .br
 225  Do not convert UID and GID into user and group names
 226 .IP "\(bu" 2
 227 \fC\fBoption_t::KDB_O_CONDENSED\fP\fP
 228 .br
 229  Less human readable, more condensed output
 230 .IP "\(bu" 2
 231 \fC\fBoption_t::KDB_O_FULLNAME\fP\fP
 232 .br
 233  The \fCuser\fP keys are exported with their full names (including user domains)
 234 .PP
 235 .RE
 236 .PP
 237 \fBSee also:\fP
 238 .RS 4
 239 \fBksToStream()\fP
 240 .RE
 241 .PP
 242 \fBReturns:\fP
 243 .RS 4
 244 number of bytes written to output
 245 .RE
 246 .PP
 247
 248 .SS "ssize_t keyToStreamBasename (const Key * key, FILE * stream, const char * parent, const size_t parentSize, option_t options)"
 249 .PP
 250 Same as \fBkeyToStream()\fP but tries to strip \fCparentSize\fP bytes from \fCkey\fP name if it matches \fCparent\fP .
 251 .PP
 252 Taking the example from \fBkeyToStream()\fP, if \fCparent\fP is \fC'system/sw/xorg'\fP, the generated string is of the form:
 253 .PP
 254 .nf
 255
 256         <key basename="Monitor/Monitor0/Name"
 257                 type="string" uid="root" gid="root" mode="0660">
 258
 259                 <value>Samsung TFT panel</value>
 260                 <comment>My monitor</comment>
 261         </key>
 262 .fi
 263 .PP
 264 .PP
 265 It usefull to produce more human readable XML output of a key when it is being represented in a context that defines the parent key name. For example:
 266 .PP
 267 .PP
 268 .nf
 269
 270         <keyset parent="user/sw">
 271                 <key basename="kdbedit"..../>
 272                 <key basename="phototools"..../>
 273                 <key basename="myapp"..../>
 274         </keyset>.fi
 275 .PP
 276 .PP
 277 In the bove example, each \fC<key>\fP entry was generated by a call to \fBkeyToStreamBasename()\fP having \fC'user/sw'\fP as \fCparent\fP .
 278 .PP
 279 This method is used when \fBksToStream()\fP is called with \fBKDBOption::KDB_O_HIER\fP option.
 280 .PP
 281 \fBParameters:\fP
 282 .RS 4
 283 \fIkey\fP the key object to work with
 284 .br
 285 \fIstream\fP the FILE where to send the stream
 286 .br
 287 \fIparentSize\fP the maximum size of \fCparent\fP that will be used. If 0, the entire \fCparent\fP will be used.
 288 .br
 289 \fIparent\fP the string (or part of it, defined by \fCparentSize\fP ) that will be used to strip from the key name.
 290 .br
 291 \fIoptions\fP Some option_t ORed:
 292 .IP "\(bu" 2
 293 \fCoption_t::KDB_O_NUMBERS\fP
 294 .br
 295  Do not convert UID and GID into user and group names
 296 .IP "\(bu" 2
 297 \fC\fBoption_t::KDB_O_CONDENSED\fP\fP
 298 .br
 299  Less human readable, more condensed output
 300 .IP "\(bu" 2
 301 \fC\fBoption_t::KDB_O_FULLNAME\fP\fP
 302 .br
 303  The \fCuser\fP keys are exported with their full names (including user domains)
 304 .PP
 305 .RE
 306 .PP
 307 \fBReturns:\fP
 308 .RS 4
 309 number of bytes written to output
 310 .RE
 311 .PP
 312
 313 .SS "int ksFromXML (KeySet * ks, int fd)"
 314 .PP
 315 FIXME: not working when fd is stdin Given a file descriptor (that can be \fCstdin\fP) for an XML file, validate schema, process nodes, convert and save it in the \fCks\fP KeySet.
 316 .PP
 317 \fBParameters:\fP
 318 .RS 4
 319 \fIks\fP keyset
 320 .br
 321 \fIfd\fP Filedeskriptor?? should be FILE*
 322 .RE
 323 .PP
 324
 325 .SS "int ksFromXMLfile (KeySet * ks, const char * filename)"
 326 .PP
 327 Given an XML \fCfilename\fP, open it, validate schema, process nodes, convert and save it in the \fCks\fP KeySet.
 328 .PP
 329 Currently, the XML file can have many root \fC<keyset>\fP and \fC<key>\fP nodes. They will all be reduced to simple keys returned in \fCks\fP.
 330 .PP
 331 To check if the xml file is valid (best before you read from it):
 332 .PP
 333 .nf
 334 #include
 335 char schemaPath[513];
 336 schemaPath[0]=0;
 337 ret=kdbGetString(handle, KDB_SCHEMA_PATH_KEY,schemaPath,sizeof(schemaPath));
 338
 339 if (ret==0) ret = isValidXML(filename,schemaPath);
 340 else ret = isValidXML(filename,KDB_SCHEMA_PATH);
 341
 342 .fi
 343 .PP
 344 .PP
 345 \fBParameters:\fP
 346 .RS 4
 347 \fIks\fP the keyset
 348 .br
 349 \fIfilename\fP the file to parse
 350 .RE
 351 .PP
 352
 353 .SS "int ksGenerate (const KeySet * ks, FILE * stream, option_t options)"
 354 .PP
 355 Generate a C-Style keyset and stream it.
 356 .PP
 357 This keyset can be used to include as c-code for applikations using elektra.
 358 .PP
 359 The options takes the same options as \fBkdbGet()\fP and \fBkdbSet()\fP.
 360 .PP
 361 \fBParameters:\fP
 362 .RS 4
 363 \fIks\fP the keyset to work with
 364 .br
 365 \fIstream\fP the file pointer where to send the stream
 366 .br
 367 \fIoptions\fP which keys not to output
 368 .RE
 369 .PP
 370 \fBReturns:\fP
 371 .RS 4
 372 1 on success
 373 .RE
 374 .PP
 375
 376 .SS "int ksOutput (const KeySet * ks, FILE * stream, option_t options)"
 377 .PP
 378 Output all information of a keyset.
 379 .PP
 380 The format is not very strict and only intend to be read by human eyes for debugging purposes. Don't rely on the format in your applications.
 381 .PP
 382 Keys are printed line per line with \fBkeyOutput()\fP.
 383 .PP
 384 The same options as \fBkeyOutput()\fP are taken and passed to them.
 385 .PP
 386 Additional KDB_O_HEADER will print the number of keys as first line.
 387 .PP
 388 \fBParameters:\fP
 389 .RS 4
 390 \fIks\fP the keyset to work with
 391 .br
 392 \fIstream\fP the file pointer where to send the stream
 393 .br
 394 \fIoptions\fP
 395 .RE
 396 .PP
 397 \fBSee also:\fP
 398 .RS 4
 399 \fBkeyOutput()\fP
 400 .RE
 401 .PP
 402 \fBReturns:\fP
 403 .RS 4
 404 1 on success
 405 .PP
 406 -1 on allocation errors
 407 .RE
 408 .PP
 409
 410 .SS "ssize_t ksToStream (const KeySet * ks, FILE * stream, option_t options)"
 411 .PP
 412 Writes to \fCstream\fP an XML version of the \fCks\fP object.
 413 .PP
 414 String generated is of the form:
 415 .PP
 416 .nf
 417
 418 <keyset>
 419 <key name=...>...</key>
 420 <key name=...>...</key>
 421 <key name=...>...</key>
 422
 423 </keyset>
 424  *
 425 .fi
 426 .PP
 427 .PP
 428 or if KDB_O_HIER is used, the form will be:
 429 .PP
 430 .nf
 431
 432 <keyset parent="user/smallest/parent/name">
 433
 434 <key basename=...>...</key>
 435 <key name=...>...</key> <!-- a key thats not under this keyset's parent -->
 436 <key basename=...>...</key>
 437
 438 </keyset>
 439  *
 440 .fi
 441 .PP
 442 .PP
 443 KDB_O_HEADER will additionally generate a header like:
 444 .PP
 445 .nf
 446
 447 <?xml version="1.0" encoding="UTF-8"?>
 448 <!-- Generated by Elektra API. Total of n keys. -->
 449 <keyset xmlns="http://www.libelektra.org"
 450         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 451         xsi:schemaLocation="http://www.libelektra.org elektra.xsd">
 452  *
 453 .fi
 454 .PP
 455 .PP
 456 \fBParameters:\fP
 457 .RS 4
 458 \fIks\fP the KeySet to serialize
 459 .br
 460 \fIstream\fP where to write output: a file or stdout
 461 .br
 462 \fIoptions\fP accepted option_t ORed:
 463 .IP "\(bu" 2
 464 \fCoption_t::KDB_O_NUMBERS\fP
 465 .br
 466  Do not convert UID and GID into user and group names.
 467 .IP "\(bu" 2
 468 \fC\fBoption_t::KDB_O_FULLNAME\fP\fP
 469 .br
 470  The \fCuser\fP keys are exported with their full names (including user domains)
 471 .IP "\(bu" 2
 472 \fC\fBoption_t::KDB_O_CONDENSED\fP\fP
 473 .br
 474  Less human readable, more condensed output.
 475 .IP "\(bu" 2
 476 \fCoption_t::KDB_O_XMLHEADERS\fP
 477 .br
 478  Exclude the correct XML headers in the output. If not used, the <?xml?> and schema info inside the <keyset> object will not be generated.
 479 .IP "\(bu" 2
 480 \fC\fBoption_t::KDB_O_HIER\fP\fP
 481 .br
 482  Will generate a <keyset> node containing a \fCparent\fP attribute, and <key> nodes with a \fCbasename\fP relative to that \fCparent\fP. The \fCparent\fP is calculated by taking the smallest key name in the keyset, so it is a good idea to have only related keys on the keyset. Otherwise, a valid consistent XML document still will be generated with regular absolute \fCname\fP attribute for the <key> nodes, due to a clever \fBkeyToStreamBasename()\fP implementation.
 483 .PP
 484 .RE
 485 .PP
 486 \fBSee also:\fP
 487 .RS 4
 488 \fBkeyToStream()\fP
 489 .PP
 490 commandList() for usage example
 491 .RE
 492 .PP
 493 \fBReturns:\fP
 494 .RS 4
 495 number of bytes written to output, or -1 if some error occurs
 496 .RE
 497 .PP
 498 \fBParameters:\fP
 499 .RS 4
 500 \fIks\fP The keyset to output
 501 .br
 502 \fIstream\fP the file pointer where to send the stream
 503 .br
 504 \fIoptions\fP see above text
 505 .RE
 506 .PP
 507