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