.\" #
.\" # Copyright (c) 2014, Juniper Networks, Inc.
.\" # All rights reserved.
.\" # This SOFTWARE is licensed under the LICENSE provided in the
.\" # ../Copyright file. By downloading, installing, copying, or 
.\" # using the SOFTWARE, you agree to be bound by the terms of that
.\" # LICENSE.
.\" # Phil Shafer, July 2014
.\" 
.Dd December 4, 2014
.Dt LIBXO 3
.Os
.Sh NAME
.Nm xo_emit , xo_emit_h , xo_emit_hv
.Nd emit formatted output based on format string and arguments
.Sh LIBRARY
.Lb libxo
.Sh SYNOPSIS
.In libxo/xo.h
.Ft xo_ssize_t
.Fn xo_emit "const char *fmt"  "..."
.Ft xo_ssize_t
.Fn xo_emit_h "xo_handle_t *xop" "const char *fmt" "..."
.Ft xo_ssize_t
.Fn xo_emit_hv "xo_handle_t *xop" "const char *fmt" "va_list vap"
.Sh DESCRIPTION
The
.Fn xo_emit
function emits formatted output using the description in a format
string along with a set of zero or more arguments, in a style similar
to
.Xr printf 3
but using a more complex format description string, as described in
.Xr xo_format 5 .
.Pp
.Fn xo_emit
uses the default output handle, as described in
.Xr libxo 3 ,
where
.Fn xo_emit_h
uses an explicit handle.
.Fn xo_emit_hv
accepts a
.Fa va_list
for additional flexibility.
.Sh EXAMPLES
In this example, a set of four values is emitted using the following
source code:
.Bd  -literal -offset indent
    xo_emit(" {:lines/%7ju} {:words/%7ju} "
            "{:characters/%7ju} {d:filename/%s}\n",
            linect, wordct, charct, file);
.Ed
Output can then be generated in various style, using 
the "--libxo" option:
.Bd  -literal -offset indent
    % 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>
.Ed
.Sh RETURN CODE
.Nm
returns a negative value on error.  If the
.Nm XOF_COLUMNS
flag has been turned on for the specific handle using
.Xr xo_set_flags 3 ,
then the number of display columns consumed by the output will be returned.
.Sh SEE ALSO
.Xr xo_open_container 3 ,
.Xr xo_open_list 3 ,
.Xr xo_format 5 ,
.Xr libxo 3
.Sh HISTORY
The
.Nm libxo
library first appeared in
.Fx 11.0 .
.Sh AUTHORS
.Nm libxo
was written by
.An Phil Shafer Aq Mt phil@freebsd.org .