LIBXO(3)

💖 LIBXO(3) — the libxo bestie era 💖

okay so welcome to LIBXO(3) from the Library Functions Manual — this is the page for the xo_emit_f-style emitting functions, and the vibe is very “pass me some flags and let’s format stuff.” iconic, honestly.

---

✨ NAME ✨

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

📚 LIBRARY 📚

library “libxo”

🌸 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 let callers pass a set of flags to the xo_emit_f emitting functions. The processing of arguments — everything except the flags — is identical to the base functions, so it’s giving “same behavior, extra flag energy.” Peep xo_emit(3) for additional information, bestie.

The only currently defined flag is XOEF_RETAIN. xo_emit_f can retain the parsed internal information related to the given format string, which lets subsequent xo_emit(3) calls use that retained information and avoid repetitive parsing of the format string. To retain parsed format information, use the XOEF_RETAIN flag to the xo_emit_f() function. slay.

⚠️ bestie, the format string must be immutable across multiple calls, 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. fr fr.

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

---

Source/version + date footer energy: Debian, April 15, 2016, LIBXO(3) — that’s a wrap, mwah 💋