LIBXO(3)

💖 LIBXO(3) 💖

okay bestie, gather round, because this is the libxo(3) page from the Library Functions Manual, and it's literally the group chat of output formatting 💅

---

✨ NAME ✨

xo_emit, xo_emit_h, xo_emit_hv — emit formatted output based on format string and arguments 🦋

---

📚 LIBRARY 📚

library “libxo” — that's the one, that's the girlies 👑

---

🎀 SYNOPSIS 🎀

#include <libxo/xo.h>

xo_ssize_t
xo_emit(const char *fmt, ...);

xo_ssize_t
xo_emit_h(xo_handle_t *xop, const char *fmt, ...);

xo_ssize_t
xo_emit_hv(xo_handle_t *xop, const char *fmt, va_list vap);

xo_ssize_t
xo_emitr(const char *fmt, ...);

---

🌈 DESCRIPTION 🌈

so the whole vibe here: xo_emit() spits out formatted output using a description that lives inside a format string, plus a set of zero or more arguments. it's giving printf(3) energy, but the format description string is way more complex and extra, and it's fully documented over in xo_format(5) ✨

xo_emit() rolls with the default output handle (that whole situation is explained in libxo(3)), whereas xo_emit_h() is the one who shows up with an explicit handle. and xo_emit_hv()? she accepts a va_list for that extra flexibility, main character behaviour honestly 🫶

---

🔥 EXAMPLES 🔥

okay so in this example, four whole values get emitted with this source code right here:

          xo_emit(" {:lines/%7ju} {:words/%7ju} "
                  "{:characters/%7ju} {d:filename/%s}\n",
                  linect, wordct, charct, file);

and then output can be generated in various style, using the "--libxo" option 🎀

          % wc /etc/motd
                25     165    1140 /etc/motd
          % wc --libxo xml,pretty,warn /etc/motd
          <wc>
            <file>
              <lines>25</lines>
              <words>165</words>
              <characters>1140</characters>
              <filename>/etc/motd</filename>
            </file>
          </wc>
          % wc --libxo json,pretty,warn /etc/motd
          {
            "wc": {
              "file": [
                {
                  "lines": 25,
                  "words": 165,
                  "characters": 1140,
                  "filename": "/etc/motd"
                }
              ]
            }
          }
          % wc --libxo html,pretty,warn /etc/motd
          <div class="line">
            <div class="text"> </div>
            <div class="data" data-tag="lines">     25</div>
            <div class="text"> </div>
            <div class="data" data-tag="words">    165</div>
            <div class="text"> </div>
            <div class="data" data-tag="characters">   1140</div>
            <div class="text"> </div>
            <div class="data" data-tag="filename">/etc/motd</div>
          </div>

🧚 Retaining Formatting Information for Constant Strings 🧚

the libxo library can cache the compiled internal version of the format, for those circumstances when the format is gonna be used over and over again — like, say, inside a loop 🔁

⚠️ bestie, listen: this cannot be used when the format string is in a dynamic buffer, because the cache keeps a reference to the static format string, which is typically a static compile-time constant value. no cap.

typically static strings get placed in an executable's ".text" segment, so libxo knows the formatting information in such static strings can be cached (retained). but shared libraries have their own ".text" segment, so without the XOEF_RETAIN flag, libxo cannot presume to retain formatting information 😭

if a caller in shared library code wants their formats retained, they need to pass the XOEF_RETAIN flag. that's the whole tea ☕

and then there's xo_emitr() — a convenience function that passes the XOEF_RETAIN flag along to xo_emit_hvf(), and she can be used in shared libraries whenever the format string is static 💅

---

💀 RETURN CODE 💀

xo_emit returns a negative value on error 😬

but if the XOF_COLUMNS flag has been turned on for the specific handle using xo_set_flags(3), then the number of display columns consumed by the output will be returned instead 📏✨

---

🌸 SEE ALSO 🌸

(ngl bestie, this section is just sitting here empty in the original — no references listed, no crumbs, nothing 🙈)

---

so that's the whole page, and for the cute sign-off: this was LIBXO(3) from the Library Functions Manual — that's the source/version energy the footer was bringing, and it didn't have a date to give us, so we're working with what we've got 🫶

stay formatted, stay iconic, and remember: the format string is static or it's nothing 💖✨🎀