LIBXO(3)

NAME
xo_emit_field - emit formatted output based on format string and arguments

LIBRARY
libxo

SYNOPSIS
#include <libxo/xo.h>
xo_ssize_t
xo_emit_field(const char *rolmod, const char *content, const char *fmt, const char *efmt, ...);
xo_ssize_t
xo_emit_field_h(xo_handle_t *xop, const char *rolmod, const char *content, const char *fmt, const, char, *efmt", ...);
xo_ssize_t
xo_emit_field_hv(xo_handle_t *xop, const char *rolmod, const char *content, const char *fmt, const char *efmt, va_list vap);

DESCRIPTION
The xo_emit_field() function emits formatted output similar to xo_emit(3) but where xo_emit() uses a single string argument containing the description for multiple fields, xo_emit_field() emits a single field using multiple arguments to contain the field description. xo_emit_field_h() adds an explicit handle to use instead of the default handle, while xo_emit_field_hv() accepts a va_list for additional flexibility.

The arguments rolmod, content, fmt, and efmt are detailed in xo_format(5). Using distinct arguments allows callers to pass the field description in pieces, rather than having to use something like snprintf(3) to build the format string required by xo_emit(). The arguments are each NUL-terminated strings. The rolmod argument contains the "role" and "modifier" portions of the field description, the content argument contains the "content" portion, and the fmt and efmt contain the "field-format" and "encoding-format" portions, respectively.

As with xo_emit, the fmt and efmt values are both optional, since the field-format string defaults to "%s", and the encoding-format's default value is derived from the field-format per xo_format(5). However, care must be taken to avoid using a value directly as the format, since characters like '{', '%', and '}' will be interpreted as formatting directives, and may cause xo_emit_field to dereference arbitrary values off the stack, leading to bugs, core files, and gnashing of teeth.

EXAMPLES
In this example, a set of four values is emitted using the following source code:

        xo_emit_field("T", title, NULL, NULL, NULL);
        xo_emit_field("Vt", "max-chaos", NULL, NULL, "  very  ");
        xo_emit_field("V", "min-chaos", "%02d", "%d", 42);
        xo_emit_field_h(NULL, ",leaf-list,quotes", "sku", "%s-%u", "%s-000-%u",
    		    "gum", 1412);

RETURN CODE
xo_emit_field returns a negative value on error. 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.

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