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