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
8 .\" # Phil Shafer, April 2016
14 .Nm xo_emit_f , xo_emit_hf , xo_emit_hvf
15 .Nd emit formatted output based on format string and arguments
21 .Fn xo_emit_f "xo_emit_flags_t flags" "const char *fmt" "..."
23 .Fn xo_emit_hf "xo_handle_t *xop" "xo_emit_flags_t flags" "const char *fmt" "..."
25 .Fn xo_emit_hvf "xo_handle_t *xop" "xo_emit_flags_t flags" "const char *fmt" "va_list vap"
27 .Fn xo_retain_clear_all "void"
29 .Fn xo_retain_clear "const char *fmt"
31 These functions allow callers to pass a set of flags to
33 emitting functions. These processing of arguments, except for
35 is identical to the base functions.
38 for additional information.
40 The only currently defined flag is
43 can retain the parsed internal information related to the given
44 format string, allowing subsequent
47 information is used, avoiding repetitive parsing of the format string.
48 To retain parsed format information, use the
54 The format string must be immutable across multiple calls to
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
61 flag must not be used.
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.
72 The retained information is kept as thread-specific data.
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.
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",
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]);
102 The return values for these functions is identical to those of their
103 traditional counterparts. See
108 .Xr xo_open_container 3 ,