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