1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
|
.\" #
.\" # 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"
.Ft xo_ssize_t
.Fn xo_emitr "const char *fmt" "..."
.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 Retaining Formatting Information for Constant Strings
.Pp
The
.Nm libxo
library can cache the compiled internal version of the format for
circumstances when the format will be used repeatedly, such as a loop.
This cannot be used when the format string is in a dynamic buffer,
since the cache retains a reference to the static format string,
typically a static compile-time constant value.
.Pp
Typically static strings are placed in an executable's ".text" segment,
so
.Nm libxo
knows that the formatting information in such static strings can be
cached (retained), but shared libraries will have their own ".text"
segment, so without the XOEF_RETAIN flag,
.Nm libxo
cannot presume to retain formatting information.
If a caller in shared library code want their formats retained, they
need to pass the XOEF_RETAIN flag.
.Pp
The
.Fn xo_emitr
function is a convenience function that passes the XOEF_RETAIN
flag to
.Fn xo_emit_hvf ,
and can be used in shared libraries when the format string is static.
.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_emit_f 3 ,
.Xo xo_emit_field 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 .
|
