LIBXO(3)               FreeBSD Library Functions Manual               LIBXO(3)

NAME

     xo_emit_f, xo_emit_hf, xo_emit_hvf - emit formatted output based on
     format string and arguments

LIBRARY

     Text, XML, JSON, and HTML Output Emission Library (libxo, -lxo)

SYNOPSIS

     #include <libxo/xo.h>

     xo_ssize_t
     xo_emit_f(xo_emit_flags_t flags, const char *fmt, ...);

     xo_ssize_t
     xo_emit_hf(xo_handle_t *xop, xo_emit_flags_t flags, const char *fmt,
         ...);

     xo_ssize_t
     xo_emit_hvf(xo_handle_t *xop, xo_emit_flags_t flags, const char *fmt,
         va_list vap);

     void
     xo_retain_clear_all(void);

     void
     xo_retain_clear(const char *fmt);

DESCRIPTION

     These functions allow callers to pass a set of flags to xo_emit_f
     emitting functions.  These processing of arguments, except for flags, is
     identical to the base functions.  See xo_emit(3) for additional
     information.

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

     The format string must be immutable across multiple calls to 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 XOEF_RETAIN flag must not be used.

     The functions xo_retain_clear() and 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.

     The retained information is kept as thread-specific data.

     Use xo_retain_clear() and 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.

EXAMPLES

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

     In this example, the caller desires to clear the retained information.

               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);

RETURN CODE

     The return values for these functions is identical to those of their
     traditional counterparts.  See xo_emit(3) for details.

SEE ALSO

     xo_emit(3), xo_open_container(3), xo_open_list(3), xo_format(5), libxo(3)

HISTORY

     The libxo library first appeared in FreeBSD 11.0.

AUTHORS

     libxo was written by Phil Shafer <phil@freebsd.org>.

FreeBSD 15.1-STABLE-HBSD        April 15, 2016                        LIBXO(3)