---
name: "xo_emit_f"
section: "3"
platform: "freebsd"
package: "base"
version: "16.0-CURRENT-20261027-61c70dc16a79"
release: "FreeBSD 16.0-CURRENT (2026-10-27)"
platforms: ["freebsd"]
url: "https://new.carta.tech/xo_emit_f"
---

# xo\_emit\_f(3)

emit formatted output based on format string and arguments

## 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 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)](/xo_emit/3.md) 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)](/xo_emit/3.md) 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)](/xo_emit/3.md) for details.

## SEE ALSO

[xo\_emit(3)](/xo_emit/3.md), [xo\_open\_container(3)](/xo_open_container/3.md), [xo\_open\_list(3)](/xo_open_list/3.md), [xo\_format(5)](/xo_format/5.md), [libxo(3)](/libxo/3.md)

## HISTORY

The **libxo** library first appeared in FreeBSD 11.0.

## AUTHORS

**libxo** was written by Phil Shafer ⟨*phil@freebsd.org*⟩.