contrib/libxo/libxo/xo.h

   1 /*
   2  * Copyright (c) 2014-2018, Juniper Networks, Inc.
   3  * All rights reserved.
   4  * This SOFTWARE is licensed under the LICENSE provided in the
   5  * ../Copyright file. By downloading, installing, copying, or otherwise
   6  * using the SOFTWARE, you agree to be bound by the terms of that
   7  * LICENSE.
   8  * Phil Shafer, July 2014
   9  */
  10
  11 /**
  12  * libxo provides a means of generating text, XML, JSON, and HTML output
  13  * using a single set of function calls, maximizing the value of output
  14  * while minimizing the cost/impact on the code.
  15  *
  16  * Full documentation is available in ./doc/libxo.txt or online at:
  17  *   http://juniper.github.io/libxo/libxo-manual.html
  18  */
  19
  20 #ifndef INCLUDE_XO_H
  21 #define INCLUDE_XO_H
  22
  23 #include <stdio.h>
  24 #include <sys/types.h>
  25 #include <stdarg.h>
  26 #include <limits.h>
  27 #include <stdlib.h>
  28 #include <errno.h>
  29
  30 #ifdef __dead2
  31 #define NORETURN __dead2
  32 #else
  33 #define NORETURN
  34 #endif /* __dead2 */
  35
  36 /*
  37  * Normally we'd use the HAVE_PRINTFLIKE define triggered by the
  38  * --enable-printflike option to configure, but we don't install
  39  * our internal "xoconfig.h", and I'd rather not.  Taking the
  40  * coward's path, we'll turn it on inside a #if that allows
  41  * others to turn it off where needed.  Not ideal, but functional.
  42  */
  43 #if !defined(NO_PRINTFLIKE)
  44 #if defined(__linux) && !defined(__printflike)
  45 #define __printflike(_x, _y) __attribute__((__format__ (__printf__, _x, _y)))
  46 #endif
  47 #define PRINTFLIKE(_x, _y) __printflike(_x, _y)
  48 #else
  49 #define PRINTFLIKE(_x, _y)
  50 #endif /* NO_PRINTFLIKE */
  51
  52 /** Formatting types */
  53 typedef unsigned short xo_style_t;
  54 #define XO_STYLE_TEXT   0       /** Generate text output */
  55 #define XO_STYLE_XML    1       /** Generate XML output */
  56 #define XO_STYLE_JSON   2       /** Generate JSON output */
  57 #define XO_STYLE_HTML   3       /** Generate HTML output */
  58 #define XO_STYLE_SDPARAMS 4     /* Generate syslog structured data params */
  59 #define XO_STYLE_ENCODER 5      /* Generate calls to external encoder */
  60
  61 /** Flags for libxo */
  62 typedef unsigned long long xo_xof_flags_t;
  63 #define XOF_BIT(_n) ((xo_xof_flags_t) 1 << (_n))
  64 #define XOF_CLOSE_FP    XOF_BIT(0) /** Close file pointer on xo_close() */
  65 #define XOF_PRETTY      XOF_BIT(1) /** Make 'pretty printed' output */
  66 #define XOF_LOG_SYSLOG  XOF_BIT(2) /** Log (on stderr) our syslog content */
  67 #define XOF_RESV3       XOF_BIT(3) /* Unused */
  68
  69 #define XOF_WARN        XOF_BIT(4) /** Generate warnings for broken calls */
  70 #define XOF_XPATH       XOF_BIT(5) /** Emit XPath attributes in HTML  */
  71 #define XOF_INFO        XOF_BIT(6) /** Emit additional info fields (HTML) */
  72 #define XOF_WARN_XML    XOF_BIT(7) /** Emit warnings in XML (on stdout) */
  73
  74 #define XOF_NO_ENV      XOF_BIT(8) /** Don't look at LIBXO_OPTIONS env var */
  75 #define XOF_NO_VA_ARG   XOF_BIT(9) /** Don't advance va_list w/ va_arg() */
  76 #define XOF_DTRT        XOF_BIT(10) /** Enable "do the right thing" mode */
  77 #define XOF_KEYS        XOF_BIT(11) /** Flag 'key' fields for xml and json */
  78
  79 #define XOF_IGNORE_CLOSE XOF_BIT(12) /** Ignore errors on close tags */
  80 #define XOF_NOT_FIRST   XOF_BIT(13) /* Not the first item (JSON)  */
  81 #define XOF_NO_LOCALE   XOF_BIT(14) /** Don't bother with locale */
  82 #define XOF_RESV15      XOF_BIT(15) /* Unused */
  83
  84 #define XOF_NO_TOP      XOF_BIT(16) /** Don't emit the top braces in JSON */
  85 #define XOF_RESV17      XOF_BIT(17) /* Unused  */
  86 #define XOF_UNITS       XOF_BIT(18) /** Encode units in XML */
  87 #define XOF_RESV19      XOF_BIT(19) /* Unused */
  88
  89 #define XOF_UNDERSCORES XOF_BIT(20) /** Replace dashes with underscores (JSON)*/
  90 #define XOF_COLUMNS     XOF_BIT(21) /** xo_emit should return a column count */
  91 #define XOF_FLUSH       XOF_BIT(22) /** Flush after each xo_emit call */
  92 #define XOF_FLUSH_LINE  XOF_BIT(23) /** Flush after each newline */
  93
  94 #define XOF_NO_CLOSE    XOF_BIT(24) /** xo_finish won't close open elements */
  95 #define XOF_COLOR_ALLOWED XOF_BIT(25) /** Allow color/effects to be enabled */
  96 #define XOF_COLOR       XOF_BIT(26) /** Enable color and effects */
  97 #define XOF_NO_HUMANIZE XOF_BIT(27) /** Block the {h:} modifier */
  98
  99 #define XOF_LOG_GETTEXT XOF_BIT(28) /** Log (stderr) gettext lookup strings */
 100 #define XOF_UTF8        XOF_BIT(29) /** Force text output to be UTF8 */
 101 #define XOF_RETAIN_ALL  XOF_BIT(30) /** Force use of XOEF_RETAIN */
 102 #define XOF_RETAIN_NONE XOF_BIT(31) /** Prevent use of XOEF_RETAIN */
 103
 104 #define XOF_COLOR_MAP   XOF_BIT(32) /** Color map has been initialized */
 105 #define XOF_CONTINUATION XOF_BIT(33) /** Continuation of previous line */
 106
 107 typedef unsigned xo_emit_flags_t; /* Flags to xo_emit() and friends */
 108 #define XOEF_RETAIN     (1<<0)    /* Retain parsed formatting information */
 109
 110 /*
 111  * The xo_info_t structure provides a mapping between names and
 112  * additional data emitted via HTML.
 113  */
 114 typedef struct xo_info_s {
 115     const char *xi_name;        /* Name of the element */
 116     const char *xi_type;        /* Type of field */
 117     const char *xi_help;        /* Description of field */
 118 } xo_info_t;
 119
 120 #define XO_INFO_NULL NULL, NULL, NULL /* Use '{ XO_INFO_NULL }' to end lists */
 121
 122 struct xo_handle_s;             /* Opaque structure forward */
 123 typedef struct xo_handle_s xo_handle_t; /* Handle for XO output */
 124
 125 /*
 126  * Early versions of the API used "int" instead of "size_t" for buffer
 127  * sizes.  We want to fix this but allow for backwards compatibility
 128  * where needed.
 129  */
 130 #ifdef XO_USE_INT_RETURN_CODES
 131 typedef int xo_ssize_t;         /* Buffer size */
 132 #else /* XO_USE_INT_RETURN_CODES */
 133 typedef ssize_t xo_ssize_t;     /* Buffer size */
 134 #endif /* XO_USE_INT_RETURN_CODES */
 135
 136 typedef xo_ssize_t (*xo_write_func_t)(void *, const char *);
 137 typedef void (*xo_close_func_t)(void *);
 138 typedef int (*xo_flush_func_t)(void *);
 139 typedef void *(*xo_realloc_func_t)(void *, size_t);
 140 typedef void (*xo_free_func_t)(void *);
 141
 142 /*
 143  * The formatter function mirrors "vsnprintf", with an additional argument
 144  * of the xo handle.  The caller should return the number of bytes _needed_
 145  * to fit the data, even if this exceeds 'len'.
 146  */
 147 typedef xo_ssize_t (*xo_formatter_t)(xo_handle_t *, char *, xo_ssize_t,
 148                                 const char *, va_list);
 149 typedef void (*xo_checkpointer_t)(xo_handle_t *, va_list, int);
 150
 151 xo_handle_t *
 152 xo_create (xo_style_t style, xo_xof_flags_t flags);
 153
 154 xo_handle_t *
 155 xo_create_to_file (FILE *fp, xo_style_t style, xo_xof_flags_t flags);
 156
 157 void
 158 xo_destroy (xo_handle_t *xop);
 159
 160 void
 161 xo_set_writer (xo_handle_t *xop, void *opaque, xo_write_func_t write_func,
 162                xo_close_func_t close_func, xo_flush_func_t flush_func);
 163
 164 void
 165 xo_set_allocator (xo_realloc_func_t realloc_func, xo_free_func_t free_func);
 166
 167 void
 168 xo_set_style (xo_handle_t *xop, xo_style_t style);
 169
 170 xo_style_t
 171 xo_get_style (xo_handle_t *xop);
 172
 173 int
 174 xo_set_style_name (xo_handle_t *xop, const char *style);
 175
 176 int
 177 xo_set_options (xo_handle_t *xop, const char *input);
 178
 179 xo_xof_flags_t
 180 xo_get_flags (xo_handle_t *xop);
 181
 182 void
 183 xo_set_flags (xo_handle_t *xop, xo_xof_flags_t flags);
 184
 185 void
 186 xo_clear_flags (xo_handle_t *xop, xo_xof_flags_t flags);
 187
 188 int
 189 xo_set_file_h (xo_handle_t *xop, FILE *fp);
 190
 191 int
 192 xo_set_file (FILE *fp);
 193
 194 void
 195 xo_set_info (xo_handle_t *xop, xo_info_t *infop, int count);
 196
 197 void
 198 xo_set_formatter (xo_handle_t *xop, xo_formatter_t func, xo_checkpointer_t);
 199
 200 void
 201 xo_set_depth (xo_handle_t *xop, int depth);
 202
 203 xo_ssize_t
 204 xo_emit_hv (xo_handle_t *xop, const char *fmt, va_list vap);
 205
 206 xo_ssize_t
 207 xo_emit_h (xo_handle_t *xop, const char *fmt, ...);
 208
 209 xo_ssize_t
 210 xo_emit (const char *fmt, ...);
 211
 212 xo_ssize_t
 213 xo_emit_hvf (xo_handle_t *xop, xo_emit_flags_t flags,
 214              const char *fmt, va_list vap);
 215
 216 xo_ssize_t
 217 xo_emit_hf (xo_handle_t *xop, xo_emit_flags_t flags, const char *fmt, ...);
 218
 219 xo_ssize_t
 220 xo_emit_f (xo_emit_flags_t flags, const char *fmt, ...);
 221
 222 PRINTFLIKE(2, 0)
 223 static inline xo_ssize_t
 224 xo_emit_hvp (xo_handle_t *xop, const char *fmt, va_list vap)
 225 {
 226     return xo_emit_hv(xop, fmt, vap);
 227 }
 228
 229 PRINTFLIKE(2, 3)
 230 static inline xo_ssize_t
 231 xo_emit_hp (xo_handle_t *xop, const char *fmt, ...)
 232 {
 233     va_list vap;
 234     va_start(vap, fmt);
 235     xo_ssize_t rc = xo_emit_hv(xop, fmt, vap);
 236     va_end(vap);
 237     return rc;
 238 }
 239
 240 PRINTFLIKE(1, 2)
 241 static inline xo_ssize_t
 242 xo_emit_p (const char *fmt, ...)
 243 {
 244     va_list vap;
 245     va_start(vap, fmt);
 246     xo_ssize_t rc = xo_emit_hv(NULL, fmt, vap);
 247     va_end(vap);
 248     return rc;
 249 }
 250
 251 PRINTFLIKE(3, 0)
 252 static inline xo_ssize_t
 253 xo_emit_hvfp (xo_handle_t *xop, xo_emit_flags_t flags,
 254               const char *fmt, va_list vap)
 255 {
 256     return xo_emit_hvf(xop, flags, fmt, vap);
 257 }
 258
 259 PRINTFLIKE(3, 4)
 260 static inline xo_ssize_t
 261 xo_emit_hfp (xo_handle_t *xop, xo_emit_flags_t flags, const char *fmt, ...)
 262 {
 263     va_list vap;
 264     va_start(vap, fmt);
 265     xo_ssize_t rc = xo_emit_hvf(xop, flags, fmt, vap);
 266     va_end(vap);
 267     return rc;
 268 }
 269
 270 PRINTFLIKE(2, 3)
 271 static inline xo_ssize_t
 272 xo_emit_fp (xo_emit_flags_t flags, const char *fmt, ...)
 273 {
 274     va_list vap;
 275     va_start(vap, fmt);
 276     xo_ssize_t rc = xo_emit_hvf(NULL, flags, fmt, vap);
 277     va_end(vap);
 278     return rc;
 279 }
 280
 281 xo_ssize_t
 282 xo_open_container_hf (xo_handle_t *xop, xo_xof_flags_t flags, const char *name);
 283
 284 xo_ssize_t
 285 xo_open_container_h (xo_handle_t *xop, const char *name);
 286
 287 xo_ssize_t
 288 xo_open_container (const char *name);
 289
 290 xo_ssize_t
 291 xo_open_container_hd (xo_handle_t *xop, const char *name);
 292
 293 xo_ssize_t
 294 xo_open_container_d (const char *name);
 295
 296 xo_ssize_t
 297 xo_close_container_h (xo_handle_t *xop, const char *name);
 298
 299 xo_ssize_t
 300 xo_close_container (const char *name);
 301
 302 xo_ssize_t
 303 xo_close_container_hd (xo_handle_t *xop);
 304
 305 xo_ssize_t
 306 xo_close_container_d (void);
 307
 308 xo_ssize_t
 309 xo_open_list_hf (xo_handle_t *xop, xo_xof_flags_t flags, const char *name);
 310
 311 xo_ssize_t
 312 xo_open_list_h (xo_handle_t *xop, const char *name);
 313
 314 xo_ssize_t
 315 xo_open_list (const char *name);
 316
 317 xo_ssize_t
 318 xo_open_list_hd (xo_handle_t *xop, const char *name);
 319
 320 xo_ssize_t
 321 xo_open_list_d (const char *name);
 322
 323 xo_ssize_t
 324 xo_close_list_h (xo_handle_t *xop, const char *name);
 325
 326 xo_ssize_t
 327 xo_close_list (const char *name);
 328
 329 xo_ssize_t
 330 xo_close_list_hd (xo_handle_t *xop);
 331
 332 xo_ssize_t
 333 xo_close_list_d (void);
 334
 335 xo_ssize_t
 336 xo_open_instance_hf (xo_handle_t *xop, xo_xof_flags_t flags, const char *name);
 337
 338 xo_ssize_t
 339 xo_open_instance_h (xo_handle_t *xop, const char *name);
 340
 341 xo_ssize_t
 342 xo_open_instance (const char *name);
 343
 344 xo_ssize_t
 345 xo_open_instance_hd (xo_handle_t *xop, const char *name);
 346
 347 xo_ssize_t
 348 xo_open_instance_d (const char *name);
 349
 350 xo_ssize_t
 351 xo_close_instance_h (xo_handle_t *xop, const char *name);
 352
 353 xo_ssize_t
 354 xo_close_instance (const char *name);
 355
 356 xo_ssize_t
 357 xo_close_instance_hd (xo_handle_t *xop);
 358
 359 xo_ssize_t
 360 xo_close_instance_d (void);
 361
 362 xo_ssize_t
 363 xo_open_marker_h (xo_handle_t *xop, const char *name);
 364
 365 xo_ssize_t
 366 xo_open_marker (const char *name);
 367
 368 xo_ssize_t
 369 xo_close_marker_h (xo_handle_t *xop, const char *name);
 370
 371 xo_ssize_t
 372 xo_close_marker (const char *name);
 373
 374 xo_ssize_t
 375 xo_attr_h (xo_handle_t *xop, const char *name, const char *fmt, ...);
 376
 377 xo_ssize_t
 378 xo_attr_hv (xo_handle_t *xop, const char *name, const char *fmt, va_list vap);
 379
 380 xo_ssize_t
 381 xo_attr (const char *name, const char *fmt, ...);
 382
 383 void
 384 xo_error_hv (xo_handle_t *xop, const char *fmt, va_list vap);
 385
 386 void
 387 xo_error_h (xo_handle_t *xop, const char *fmt, ...);
 388
 389 void
 390 xo_error (const char *fmt, ...);
 391
 392 xo_ssize_t
 393 xo_flush_h (xo_handle_t *xop);
 394
 395 xo_ssize_t
 396 xo_flush (void);
 397
 398 xo_ssize_t
 399 xo_finish_h (xo_handle_t *xop);
 400
 401 xo_ssize_t
 402 xo_finish (void);
 403
 404 void
 405 xo_finish_atexit (void);
 406
 407 void
 408 xo_set_leading_xpath (xo_handle_t *xop, const char *path);
 409
 410 void
 411 xo_warn_hc (xo_handle_t *xop, int code, const char *fmt, ...) PRINTFLIKE(3, 4);
 412
 413 void
 414 xo_warn_c (int code, const char *fmt, ...) PRINTFLIKE(2, 3);
 415
 416 void
 417 xo_warn (const char *fmt, ...) PRINTFLIKE(1, 2);
 418
 419 void
 420 xo_warnx (const char *fmt, ...) PRINTFLIKE(1, 2);
 421
 422 void
 423 xo_err (int eval, const char *fmt, ...) NORETURN PRINTFLIKE(2, 3);
 424
 425 void
 426 xo_errx (int eval, const char *fmt, ...) NORETURN PRINTFLIKE(2, 3);
 427
 428 void
 429 xo_errc (int eval, int code, const char *fmt, ...) NORETURN PRINTFLIKE(3, 4);
 430
 431 void
 432 xo_message_hcv (xo_handle_t *xop, int code, const char *fmt, va_list vap) PRINTFLIKE(3, 0);
 433
 434 void
 435 xo_message_hc (xo_handle_t *xop, int code, const char *fmt, ...) PRINTFLIKE(3, 4);
 436
 437 void
 438 xo_message_c (int code, const char *fmt, ...) PRINTFLIKE(2, 3);
 439
 440 void
 441 xo_message_e (const char *fmt, ...) PRINTFLIKE(1, 2);
 442
 443 void
 444 xo_message (const char *fmt, ...) PRINTFLIKE(1, 2);
 445
 446 void
 447 xo_emit_warn_hcv (xo_handle_t *xop, int as_warning, int code,
 448                   const char *fmt, va_list vap);
 449
 450 void
 451 xo_emit_warn_hc (xo_handle_t *xop, int code, const char *fmt, ...);
 452
 453 void
 454 xo_emit_warn_c (int code, const char *fmt, ...);
 455
 456 void
 457 xo_emit_warn (const char *fmt, ...);
 458
 459 void
 460 xo_emit_warnx (const char *fmt, ...);
 461
 462 void
 463 xo_emit_err (int eval, const char *fmt, ...) NORETURN;
 464
 465 void
 466 xo_emit_errx (int eval, const char *fmt, ...) NORETURN;
 467
 468 void
 469 xo_emit_errc (int eval, int code, const char *fmt, ...) NORETURN;
 470
 471 PRINTFLIKE(4, 0)
 472 static inline void
 473 xo_emit_warn_hcvp (xo_handle_t *xop, int as_warning, int code,
 474                   const char *fmt, va_list vap)
 475 {
 476     xo_emit_warn_hcv(xop, as_warning, code, fmt, vap);
 477 }
 478
 479 PRINTFLIKE(3, 4)
 480 static inline void
 481 xo_emit_warn_hcp (xo_handle_t *xop, int code, const char *fmt, ...)
 482 {
 483     va_list vap;
 484     va_start(vap, fmt);
 485     xo_emit_warn_hcv(xop, 1, code, fmt, vap);
 486     va_end(vap);
 487 }
 488
 489 PRINTFLIKE(2, 3)
 490 static inline void
 491 xo_emit_warn_cp (int code, const char *fmt, ...)
 492 {
 493     va_list vap;
 494     va_start(vap, fmt);
 495     xo_emit_warn_hcv(NULL, 1, code, fmt, vap);
 496     va_end(vap);
 497 }
 498
 499 PRINTFLIKE(1, 2)
 500 static inline void
 501 xo_emit_warn_p (const char *fmt, ...)
 502 {
 503     int code = errno;
 504     va_list vap;
 505     va_start(vap, fmt);
 506     xo_emit_warn_hcv(NULL, 1, code, fmt, vap);
 507     va_end(vap);
 508 }
 509
 510 PRINTFLIKE(1, 2)
 511 static inline void
 512 xo_emit_warnx_p (const char *fmt, ...)
 513 {
 514     va_list vap;
 515     va_start(vap, fmt);
 516     xo_emit_warn_hcv(NULL, 1, -1, fmt, vap);
 517     va_end(vap);
 518 }
 519
 520 NORETURN PRINTFLIKE(2, 3)
 521 static inline void
 522 xo_emit_err_p (int eval, const char *fmt, ...)
 523 {
 524     int code = errno;
 525     va_list vap;
 526     va_start(vap, fmt);
 527     xo_emit_warn_hcv(NULL, 0, code, fmt, vap);
 528     va_end(vap);
 529
 530     exit(eval);
 531 }
 532
 533 PRINTFLIKE(2, 3)
 534 static inline void
 535 xo_emit_errx_p (int eval, const char *fmt, ...)
 536 {
 537     va_list vap;
 538     va_start(vap, fmt);
 539     xo_emit_warn_hcv(NULL, 0, -1, fmt, vap);
 540     va_end(vap);
 541     exit(eval);
 542 }
 543
 544 PRINTFLIKE(3, 4)
 545 static inline void
 546 xo_emit_errc_p (int eval, int code, const char *fmt, ...)
 547 {
 548     va_list vap;
 549     va_start(vap, fmt);
 550     xo_emit_warn_hcv(NULL, 0, code, fmt, vap);
 551     va_end(vap);
 552     exit(eval);
 553 }
 554
 555 void
 556 xo_emit_err_v (int eval, int code, const char *fmt, va_list vap) NORETURN PRINTFLIKE(3, 0);
 557
 558 void
 559 xo_no_setlocale (void);
 560
 561 /**
 562  * @brief Lift libxo-specific arguments from a set of arguments
 563  *
 564  * libxo-enable programs typically use command line options to enable
 565  * all the nifty-cool libxo features.  xo_parse_args() makes this simple
 566  * by pre-processing the command line arguments given to main(), handling
 567  * and removing the libxo-specific ones, meaning anything starting with
 568  * "--libxo".  A full description of these arguments is in the base
 569  * documentation.
 570  * @param[in] argc Number of arguments (ala #main())
 571  * @param[in] argc Array of argument strings (ala #main())
 572  * @return New number of arguments, or -1 for failure.
 573  */
 574 int
 575 xo_parse_args (int argc, char **argv);
 576
 577 /**
 578  * This is the "magic" number returned by libxo-supporting commands
 579  * when passed the equally magic "--libxo-check" option.  If you
 580  * return this, we can (unsafely) assume that since you know the magic
 581  * handshake, you'll happily handle future --libxo options and not do
 582  * something violent like reboot the box or create another hole in the
 583  * ozone layer.
 584  */
 585 #define XO_HAS_LIBXO    121
 586
 587 /**
 588  * externs for libxo's version number strings
 589  */
 590 extern const char xo_version[];       /** Base version triple string */
 591 extern const char xo_version_extra[]; /** Extra version magic content */
 592
 593 /**
 594  * @brief Dump the internal stack of a libxo handle.
 595  *
 596  * This diagnostic function is something I will ask you to call from
 597  * your program when you write to tell me libxo has gone bat-stink
 598  * crazy and has discarded your list or container or content.  Output
 599  * content will be what we lovingly call "developer entertainment".
 600  * @param[in] xop A valid libxo handle, or NULL for the default handle
 601  */
 602 void
 603 xo_dump_stack (xo_handle_t *xop);
 604
 605 /**
 606  * @brief Recode the name of the program, suitable for error output.
 607  *
 608  * libxo will record the given name for use while generating error
 609  * messages.  The contents are not copied, so the value must continue
 610  * to point to a valid memory location.  This allows the caller to change
 611  * the value, but requires the caller to manage the memory.  Typically
 612  * this is called with argv[0] from main().
 613  * @param[in] name The name of the current application program
 614  */
 615 void
 616 xo_set_program (const char *name);
 617
 618 /**
 619  * @brief Add a version string to the output, where possible.
 620  *
 621  * Adds a version number to the output, suitable for tracking
 622  * changes in the content.  This is only important for the "encoding"
 623  * format styles (XML and JSON) and allows a user of the data to
 624  * discern which version of the data model is in use.
 625  * @param[in] version The version number, encoded as a string
 626  */
 627 void
 628 xo_set_version (const char *version);
 629
 630 /**
 631  * #xo_set_version with a handle.
 632  * @param[in] xop A valid libxo handle, or NULL for the default handle
 633  * @param[in] version The version number, encoded as a string
 634  */
 635 void
 636 xo_set_version_h (xo_handle_t *xop, const char *version);
 637
 638 void
 639 xo_open_log (const char *ident, int logopt, int facility);
 640
 641 void
 642 xo_close_log (void);
 643
 644 int
 645 xo_set_logmask (int maskpri);
 646
 647 void
 648 xo_set_unit_test_mode (int value);
 649
 650 void
 651 xo_syslog (int priority, const char *name, const char *message, ...);
 652
 653 void
 654 xo_vsyslog (int priority, const char *name, const char *message, va_list args);
 655
 656 typedef void (*xo_syslog_open_t)(void);
 657 typedef void (*xo_syslog_send_t)(const char *full_msg,
 658                                  const char *v0_hdr, const char *text_only);
 659 typedef void (*xo_syslog_close_t)(void);
 660
 661 void
 662 xo_set_syslog_handler (xo_syslog_open_t open_func, xo_syslog_send_t send_func,
 663                        xo_syslog_close_t close_func);
 664
 665 void
 666 xo_set_syslog_enterprise_id (unsigned short eid);
 667
 668 typedef void (*xo_simplify_field_func_t)(const char *, unsigned, int);
 669
 670 char *
 671 xo_simplify_format (xo_handle_t *xop, const char *fmt, int with_numbers,
 672                     xo_simplify_field_func_t field_cb);
 673
 674 xo_ssize_t
 675 xo_emit_field_hv (xo_handle_t *xop, const char *rolmod, const char *contents,
 676                   const char *fmt, const char *efmt,
 677                   va_list vap);
 678
 679 xo_ssize_t
 680 xo_emit_field_h (xo_handle_t *xop, const char *rolmod, const char *contents,
 681                  const char *fmt, const char *efmt, ...);
 682
 683 xo_ssize_t
 684 xo_emit_field (const char *rolmod, const char *contents,
 685                const char *fmt, const char *efmt, ...);
 686
 687 void
 688 xo_retain_clear_all (void);
 689
 690 void
 691 xo_retain_clear (const char *fmt);
 692
 693 #endif /* INCLUDE_XO_H */