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>.