contrib/libxo/libxo/xo_emit_f.3

   1 .\" #
   2 .\" # Copyright (c) 2016, 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
   6 .\" # using the SOFTWARE, you agree to be bound by the terms of that
   7 .\" # LICENSE.
   8 .\" # Phil Shafer, April 2016
   9 .\"
  10 .Dd April 15, 2016
  11 .Dt LIBXO 3
  12 .Os
  13 .Sh NAME
  14 .Nm xo_emit_f , xo_emit_hf , xo_emit_hvf
  15 .Nd emit formatted output based on format string and arguments
  16 .Sh LIBRARY
  17 .Lb libxo
  18 .Sh SYNOPSIS
  19 .In libxo/xo.h
  20 .Ft int
  21 .Fn xo_emit_f "xo_emit_flags_t flags" "const char *fmt"  "..."
  22 .Ft int
  23 .Fn xo_emit_hf "xo_handle_t *xop" "xo_emit_flags_t flags" "const char *fmt" "..."
  24 .Ft int
  25 .Fn xo_emit_hvf "xo_handle_t *xop" "xo_emit_flags_t flags" "const char *fmt" "va_list vap"
  26 .Ft void
  27 .Fn xo_retain_clear_all "void"
  28 .Ft void
  29 .Fn xo_retain_clear "const char *fmt"
  30 .Sh DESCRIPTION
  31 These functions allow callers to pass a set of flags to
  32 .Nm
  33 emitting functions.  These processing of arguments, except for
  34 .Fa flags ,
  35 is identical to the base functions.
  36 See
  37 .Xr xo_emit 3
  38 for additional information.
  39 .Pp
  40 The only currently defined flag is
  41 .Dv XOEF_RETAIN .
  42 .Nm
  43 can retain the parsed internal information related to the given
  44 format string, allowing subsequent
  45 .Xr xo_emit 3
  46 calls, the retained
  47 information is used, avoiding repetitive parsing of the format string.
  48 To retain parsed format information, use the
  49 .Dv XOEF_RETAIN
  50 flag to the
  51 .Fn xo_emit_f
  52 function.
  53 .Pp
  54 The format string must be immutable across multiple calls to
  55 .Xn xo_emit_f ,
  56 since the library retains the string.
  57 Typically this is done by using
  58 static constant strings, such as string literals. If the string is not
  59 immutable, the
  60 .Dv XOEF_RETAIN
  61 flag must not be used.
  62 .Pp
  63 The functions
  64 .Fn xo_retain_clear
  65 and
  66 .Fn xo_retain_clear_all
  67 release internal information on either a single format string or all
  68 format strings, respectively.
  69 Neither is required, but the library will
  70 retain this information until it is cleared or the process exits.
  71 .Pp
  72 The retained information is kept as thread-specific data.
  73 .Pp
  74 Use
  75 .Fn xo_retain_clear
  76 and
  77 .Fn xo_retain_clear_all
  78 to clear the retained information, clearing the retained information
  79 for either a specific format string or all format strings, respectively.
  80 These functions are only needed when the calling application wants to
  81 clear this information; they are not generally needed.
  82 .Sh EXAMPLES
  83 .Pp
  84 .Bd  -literal -offset indent
  85     for (i = 0; i < 1000; i++) {
  86         xo_open_instance("item");
  87         xo_emit_f(XOEF_RETAIN, "{:name}  {:count/%d}\n",
  88                   name[i], count[i]);
  89     }
  90 .Ed
  91 .Pp
  92 In this example, the caller desires to clear the retained information.
  93 .Bd  -literal -offset indent
  94     const char *fmt = "{:name}  {:count/%d}\n";
  95     for (i = 0; i < 1000; i++) {
  96         xo_open_instance("item");
  97         xo_emit_f(XOEF_RETAIN, fmt, name[i], count[i]);
  98     }
  99     xo_retain_clear(fmt);
 100 .Ed
 101 .Sh RETURN CODE
 102 The return values for these functions is identical to those of their
 103 traditional counterparts.  See
 104 .Xr xo_emit 3
 105 for details.
 106 .Sh SEE ALSO
 107 .Xr xo_emit 3 ,
 108 .Xr xo_open_container 3 ,
 109 .Xr xo_open_list 3 ,
 110 .Xr xo_format 5 ,
 111 .Xr libxo 3