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