LIBXO(3)

✨ LIBXO(3) — the manual, but make it cute ✨

okay so bestie, we're in the Library Functions Manual today and we're talking about LIBXO(3) — the marker functions. yes, the ones that gatekeep your closing calls. let's get into it 💅

---

🌸 NAME 🌸

xo_open_marker, xo_open_marker_h, xo_close_marker, xo_close_marker_h — the little icons that prevent (and allow) closing of open constructs. like, they literally decide what's allowed to close and what isn't. no cap.

---

📚 LIBRARY 📚

library “libxo” — that's the one, that's the girl 🫶

---

🎀 SYNOPSIS 🎀

#include <libxo/xo.h>

xo_ssize_t
xo_open_marker(const char *name);

xo_ssize_t
xo_open_marker_h(xo_handle_t *handle, const char *name);

xo_ssize_t
xo_close_marker(const char *name);

xo_ssize_t
xo_close_marker_h(xo_handle_t *handle, const char *name);

---

💖 DESCRIPTION 💖

so here's the tea, bestie. libxo represents hierarchy using exactly two constructs: “containers” and “lists”. that's it, that's the whole architecture, iconic.

A marker can be used to affect how open constructs get closed — either by preventing their closure (implicit or explicit) or by forcing their closure. While a marker is open, no other open constructs can be closed. and when a marker is closed? every construct that opened since that marker was opened gets closed too. it's giving "you came in with me, you leave with me" energy 😤

A marker basically “freezes” any open constructs. Calls to xo_close_*() functions that would normally close them just get ignored — effectively blocking their closure. like, blocked. blocked blocked. 🙈

However! when xo_close_marker() is called, any containers, lists, or leaf-lists opened since the matching xo_open_marker() call will be closed and the marker discarded. periodt.

Markers use names which are not user-visible, which means the caller gets to pick whatever internal names they want. the marker itself has no value and is not emitted in any form. it's a silent icon, a behind-the-scenes queen, we love that for her 👑

To open a marker, call xo_open_marker() or xo_open_marker_h(). the former uses the default handle, and the latter accepts a specific handle. choose your fighter 💅

To close a marker, use the xo_close_marker() or xo_close_marker_h() functions.

Each open call must have a matching close call. every single one. no skipping. i'm watching 👀

---

🐟 the example where the marker blocks a close 🐟

In this example, the xo_close_container() call on line [1] will be ignored, since the open marker "outer" will prevent close of any open constructs that precede it. The xo_close_marker() call on line [2] will close the "system" container, since it was opened after the "outer" marker.

Example:

xo_open_container("top");
xo_open_marker("outer");
xo_open_container("system");
xo_emit("{:host-name/%s%s%s", hostname,
        domainname ? "." : "", domainname ?: "");
xo_close_container("top");   /* [1] */
xo_close_marker("outer");    /* [2] */
xo_close_container("top");

---

🧜 the example where we whiffle through fish 🧜

In this example, the code whiffles through a list of fish, calling a function to emit details about each fish. The marker "fish-guts" is used to ensure that any constructs opened by the function are closed properly. clean-up on aisle fish 🐠✨

for (i = 0; fish[i]; i++) {
    xo_open_instance("fish");
    xo_open_marker("fish-guts");
    dump_fish_details(i);
    xo_close_marker("fish-guts");
}

---

👀 SEE ALSO 👀

• xo_emit(3)
• libxo(3)

go read your sisters, they're slay too 💜

---

📜 HISTORY 📜

The libxo library first appeared in FreeBSD 11.0. a debut, a moment, a cultural reset 🌈

---

💌 AUTHORS 💌

libxo was written by Phil Shafer <phil@freebsd.org>. thank you king 🫡

---

🦋 ADDITIONAL DOCUMENTATION 🦋

FreeBSD uses libxo version 1.7.5. Complete documentation can be found on github:

https://juniper.github.io/libxo/1.7.5/html/index.html

libxo lives on github as:

https://github.com/Juniper/libxo

The latest release of libxo is available at:

https://github.com/Juniper/libxo/releases

---

⭐ HISTORY (the second one, yes there are two, and yes we're doing both) ⭐

The libxo library was added in FreeBSD 11.0. same era, different sentence. she said it twice because it's that important 💅

---

🌟 AUTHOR 🌟

Phil Shafer

---

and that's the whole page bestie!! this one shipped on Debian, dated January 22, 2015, tagged LIBXO(3) — mwah, go open a marker and freeze something, ily 🎀✨