#
 # Copyright (c) 2016, Juniper Networks, Inc.
 # All rights reserved.
 # This SOFTWARE is licensed under the LICENSE provided in the
 # ../Copyright file. By downloading, installing, copying, or 
 # using the SOFTWARE, you agree to be bound by the terms of that
 # LICENSE.
 # Phil Shafer, April 2016
 
.Dd April 15, 2016
.Dt LIBXO 3
.Os
.Sh NAME
.Nm xo_emit_f , xo_emit_hf , xo_emit_hvf
.Nd emit formatted output based on format string and arguments
.Sh LIBRARY
.Lb libxo
.Sh SYNOPSIS
n libxo/xo.h .Ft int
.Fn xo_emit_f "xo_emit_flags_t flags" "const char *fmt" "..."
.Ft int
.Fn xo_emit_hf "xo_handle_t *xop" "xo_emit_flags_t flags" "const char *fmt" "..."
.Ft int
.Fn xo_emit_hvf "xo_handle_t *xop" "xo_emit_flags_t flags" "const char *fmt" "va_list vap"
.Ft void
.Fn xo_retain_clear_all "void"
.Ft void
.Fn xo_retain_clear "const char *fmt"
.Sh DESCRIPTION
These functions allow callers to pass a set of flags to
.Nm
emitting functions. These processing of arguments, except for
.Fa flags ,
is identical to the base functions.
See
.Xr xo_emit 3
for additional information.

p
The only currently defined flag is
.Dv XOEF_RETAIN .
.Nm
can retain the parsed internal information related to the given
format string, allowing subsequent
.Xr xo_emit 3
calls, the retained
information is used, avoiding repetitive parsing of the format string.
To retain parsed format information, use the
.Dv XOEF_RETAIN
flag to the
.Fn xo_emit_f
function.

p
The format string must be immutable across multiple calls to
.Xn xo_emit_f ,
since the library retains the string.
Typically this is done by using
static constant strings, such as string literals. If the string is not
immutable, the
.Dv XOEF_RETAIN
flag must not be used.

p
The functions
.Fn xo_retain_clear
and
.Fn xo_retain_clear_all
release internal information on either a single format string or all
format strings, respectively.
Neither is required, but the library will
retain this information until it is cleared or the process exits.

p
The retained information is kept as thread-specific data.

p
Use
.Fn xo_retain_clear
and
.Fn xo_retain_clear_all
to clear the retained information, clearing the retained information
for either a specific format string or all format strings, respectively.
These functions are only needed when the calling application wants to
clear this information; they are not generally needed.
.Sh EXAMPLES

p
d -literal -offset indent  for (i = 0; i < 1000; i++) {
 xo_open_instance("item");
 xo_emit_f(XOEF_RETAIN, "{:name} {:count/%d}\n",
 name[i], count[i]);
 }
.Ed

p
In this example, the caller desires to clear the retained information.
d -literal -offset indent  const char *fmt = "{:name} {:count/%d}\n";
 for (i = 0; i < 1000; i++) {
 xo_open_instance("item");
 xo_emit_f(XOEF_RETAIN, fmt, name[i], count[i]);
 }
 xo_retain_clear(fmt);
.Ed
.Sh RETURN CODE
The return values for these functions is identical to those of their
traditional counterparts. See
.Xr xo_emit 3
for details.
.Sh SEE ALSO
.Xr xo_emit 3 ,
.Xr xo_open_container 3 ,
.Xr xo_open_list 3 ,
.Xr xo_format 5 ,
.Xr libxo 3
.Sh HISTORY
The
.Nm libxo
library first appeared in
.Fx 11.0 .
.Sh AUTHORS
.Nm libxo
was written by
.An Phil Shafer Aq Mt phil@freebsd.org .