1 .\"
2 .\" This file and its contents are supplied under the terms of the
3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
4 .\" You may only use this file in accordance with the terms of version
5 .\" 1.0 of the CDDL.
6 .\"
7 .\" A full copy of the text of the CDDL should have accompanied this
8 .\" source. A copy of the CDDL is also available via the Internet at
9 .\" http://www.illumos.org/license/CDDL.
10 .\"
11 .\"
12 .\" Copyright 2010 Sun Microsystems, Inc. All rights reserved.
13 .\" Copyright 2017 Nexenta Systems, Inc.
14 .\" Copyright 2018 Joyent, Inc.
15 .\"
16 .Dd December 20, 2018
17 .Dt OFMT 3OFMT
18 .Os
19 .Sh NAME
20 .Nm ofmt_open ,
21 .Nm ofmt_print ,
22 .Nm ofmt_update_winsize ,
23 .Nm ofmt_strerror ,
24 .Nm ofmt_close
25 .Nd data structures and routines for printing output
26 .Sh LIBRARY
27 .Lb libofmt
28 .Sh SYNOPSIS
29 .In ofmt.h
30 .Ft ofmt_status_t
31 .Fo ofmt_open
32 .Fa "const char *fields"
33 .Fa "const ofmt_field_t *template"
34 .Fa "uint_t flags"
35 .Fa "uint_t maxcols"
36 .Fa "ofmt_handle_t *ofmt"
37 .Fc
38 .Ft void
39 .Fo ofmt_print
40 .Fa "ofmt_handle_t ofmt"
41 .Fa "void *cbarg"
42 .Fc
43 .Ft void
44 .Fo ofmt_update_winsize
45 .Fa "ofmt_handle_t ofmt"
46 .Fc
47 .Ft "char *"
48 .Fo ofmt_strerror
49 .Fa "ofmt_handle_t ofmt"
50 .Fa "ofmt_status_t error"
51 .Fa "char *buf"
52 .Fa "uint_t bufsize"
53 .Fc
54 .Ft void
55 .Fo ofmt_close
56 .Fa "ofmt_handle_t ofmt"
57 .Fc
58 .Sh DESCRIPTION
59 The
60 .Nm libofmt
61 library provides data structures and routines for printing output.
62 .Pp
63 Currently this is an internal interface.
64 The interface can and will change without notice as the project needs, at any
65 time.
66 .Pp
67 All output is assumed to be in a columnar format, where each column represents
68 a field to be printed out.
69 Multiple fields in parsable output are separated by
70 .Sq \&: ,
71 with the
72 .Sq \&:
73 character itself escaped by a
74 .Sq \e
75 .Po e.g., IPv6 addresses may be printed as
76 .Qq fe80\e:\e:1
77 .Pc ;
78 single field output is printed as-is.
79 In multiline mode, every
80 .Bq field,value
81 pair is printed in a line of its own, thus:
82 .Qq field: value .
83 .Ss Data Structures
84 The
85 .Vt ofmt_field_t
86 data structure used in
87 .Sx ofmt_open
88 is defined as follows:
89 .Bd -literal
90 typedef struct ofmt_field_s {
91 char *of_name; /* column name */
92 uint_t of_width; /* output column width */
93 uint_t of_id; /* implementation specific cookie */
94 ofmt_cb_t *of_cb; /* callback function defined by caller */
95 } ofmt_field_t;
96 .Ed
97 .Pp
98 The
99 .Vt ofmt_arg_t
100 data structure which is passed to callback function is defined as follows:
101 .Bd -literal
102 typedef struct ofmt_arg_s {
103 uint_t ofmt_id; /* implementation specific cookie */
104 uint_t ofmt_width; /* output column width */
105 uint_t ofmt_index; /* unused */
106 void *ofmt_cbarg; /* argument passed to ofmt_print() */
107 } ofmt_arg_t;
108 .Ed
109 .Ss Fn ofmt_open
110 The
111 .Fn ofmt_open
112 function opens a handle returned in
113 .Fa ofmt
114 for each set of fields to be printed.
115 .Pp
116 .Fa fields
117 is a comma-separated list of the fields that have been selected for output
118 .Po typically the string passed to
119 .Fl o
120 in the command-line
121 .Pc .
122 Columns selected for output are identified by a match between the
123 .Va of_name
124 value in the
125 .Fa template
126 and the
127 .Fa fields
128 requested.
129 In human-friendly
130 .Pq non machine-parsable
131 mode,
132 .Dv NULL
133 .Fa fields ,
134 or a value of
135 .Qq all
136 is treated as a request to print all allowable fields that fit other applicable
137 constraints.
138 .Pp
139 .Fa template
140 specifies the list of supported fields, along with formatting information
141 .Pq e.g., field width ,
142 and a pointer to a callback function that can provide a string representation of
143 the value to be printed out.
144 The set of supported fields must be a
145 .Dv NULL
146 terminated array of type
147 .Vt ofmt_field_t ,
148 described in
149 .Sx Data Structures ,
150 as follows:
151 .Bd -literal -offset indent
152 {<of_name>, <of_width>, <of_id>, <of_cb> },
153 \&.\&.\&.
154 {<of_name>, <of_width>, <of_id>, <of_cb> },
155 {NULL, 0, 0, NULL}
156 .Ed
157 .Pp
158 .Va of_cb
159 is the application-specified callback function with the following prototype that
160 provides a string representation of the value to be printed for the field:
161 .Bd -literal -offset indent
162 boolean_t (*of_cb)(ofmt_arg_t *ofmt_arg, char *buf, uint_t bufsize)
163 .Ed
164 .Pp
165 The callback must not write beyond
166 .Fa bufsize
167 bytes of the string form into
168 .Fa buf .
169 If the function successfully translates the field into its string
170 representation and places it into
171 .Fa buf ,
172 then the callback function should return
173 .Dv B_TRUE .
174 Otherwise, the callback function should return
175 .Dv B_FALSE .
176 .Pp
177 The interpretation of the
178 .Va of_id
179 field is completely private to the caller, and can be optionally used by the
180 callback function as a cookie to identify the field being printed when a single
181 callback function is shared between multiple
182 .Fa template
183 entries.
184 .Pp
185 The
186 .Fa flags
187 can be any valid combination of the following:
188 .Pp
189 .Bl -tag -width "OFMT_MULTILINE" -compact
190 .It Dv OFMT_PARSABLE
191 Machine-parsable mode.
192 Specifying a null or empty
193 .Va fields
194 in the machine-parsable mode will result in a returned error value of
195 .Dv OFMT_EPARSENONE .
196 An attempt to create a handle in machine-parsable mode with the
197 .Fa fields
198 set to
199 .Qq all
200 will result in a returned error value of
201 .Dv OFMT_EPARSEALL .
202 .It Dv OFMT_WRAP
203 Wrap output if field width is exceeded.
204 Currently output is wrapped at whitespace or comma characters.
205 .It Dv OFMT_MULTILINE
206 Multiline mode.
207 Specifying both
208 .Dv OFMT_MULTILINE
209 and
210 .Dv OFMT_PARSABLE
211 will result in
212 .Dv OFMT_EPARSEMULTI .
213 .It Dv OFMT_RIGHTJUST
214 Right justified output.
215 .El
216 .Pp
217 The non-zero
218 .Fa maxcols
219 limits the number of output columns.
220 .Ss Fn ofmt_print
221 The
222 .Fn ofmt_print
223 function prints a row of output.
224 .Pp
225 .Fa cbarg
226 points at the arguments to be passed to the callback function for each column in
227 the row.
228 The call to
229 .Fn ofmt_print
230 will result in the callback function of each selected field invoked with
231 .Va of_id ,
232 .Va of_width
233 and
234 .Fa cbarg
235 embedded in
236 .Fa ofmt_arg ,
237 described in
238 .Sx Data Structures .
239 .Pp
240 The callback function should fill
241 .Fa buf
242 with the string to be printed for the field using the data in
243 .Fa cbarg .
244 .Ss Fn ofmt_update_winsize
245 The
246 .Fn ofmt_update_winsize
247 function updates the window size information
248 .Pq which is initially computed when the handle is created
249 in the
250 .Fa ofmt .
251 If the
252 .Dv TIOCGWINSZ
253 ioctl fails, the window size is set to 80x24.
254 .Ss Fn ofmt_strerror
255 The
256 .Fn ofmt_strerror
257 function returns error diagnostics in
258 .Fa buf
259 using the information in the
260 .Fa ofmt
261 and
262 .Fa error .
263 .Pp
264 Using a
265 .Fa buf
266 size of
267 .Dv OFMT_BUFSIZE
268 is recommended.
269 .Ss Fn ofmt_close
270 The
271 .Fn ofmt_close
272 function frees any resources allocated for the handle after printing is
273 completed.
274 .Sh RETURN VALUES
275 If successful, the
276 .Fn ofmt_open
277 function will return
278 .Dv OFMT_SUCCESS ,
279 with a non-null
280 .Fa ofmt_handle .
281 The function returns one of the failure codes
282 .Po enumerated in
283 .Vt ofmt_status_t
284 .Pc
285 listed below otherwise:
286 .Pp
287 .Bl -tag -width "OFMT_ENOTEMPLATE" -compact
288 .It Dv OFMT_ENOMEM
289 out of memory
290 .It Dv OFMT_EBADFIELDS
291 one or more bad fields with good fields
292 .It Dv OFMT_ENOFIELDS
293 no valid output fields
294 .It Dv OFMT_EPARSEALL
295 "all" is invalid in parsable mode
296 .It Dv OFMT_EPARSENONE
297 output fields missing in parsable mode
298 .It Dv OFMT_EPARSEWRAP
299 parsable mode incompatible with wrap mode
300 .It Dv OFMT_ENOTEMPLATE
301 no template provided for fields
302 .It Dv OFMT_EPARSEMULTI
303 parsable and multiline don't mix
304 .El
305 .Pp
306 More information about the type of failure can be obtained by calling
307 .Fn ofmt_strerror .
308 .Pp
309 The
310 .Fn ofmt_strerror
311 function returns the
312 .Fa buf .
313 .Sh INTERFACE STABILITY
314 .Sy Private .
315 .Sh SEE ALSO
316 .Xr ioctl 2 ,
317 .Xr strerror 3C ,
318 .Xr attributes 5