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
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.
|
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
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.
|