mirror of https://github.com/F-Stack/f-stack.git
112 lines
3.1 KiB
Groff
112 lines
3.1 KiB
Groff
.\" #
|
|
.\" # 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
|
|
.In 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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
The retained information is kept as thread-specific data.
|
|
.Pp
|
|
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
|
|
.Pp
|
|
.Bd -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
|
|
.Pp
|
|
In this example, the caller desires to clear the retained information.
|
|
.Bd -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
|