8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 * or http://www.opensolaris.org/os/licensing.
10 * See the License for the specific language governing permissions
11 * and limitations under the License.
12 *
13 * When distributing Covered Code, include this CDDL HEADER in each
14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 * If applicable, add the following below this CDDL HEADER, with the
16 * fields enclosed by brackets "[]" replaced with your own identifying
17 * information: Portions Copyright [yyyy] [name of copyright owner]
18 *
19 * CDDL HEADER END
20 */
21
22 /*
23 * Copyright 2010 Sun Microsystems, Inc. All rights reserved.
24 * Use is subject to license terms.
25 */
26
27 /*
28 * Copyright 2017 Joyent, Inc.
29 */
30
31 #ifndef _OFMT_H
32 #define _OFMT_H
33
34 /*
35 * Data structures and routines for printing output.
36 *
37 * All output is assumed to be in a columnar format, where each column
38 * represents a field to be printed out. Multiple fields in parsable output
39 * are separated by ':', with the ':' character itself escaped by a \
40 * (e.g., IPv6 addresses may be printed as "fe80\:\:1"); single field output
41 * is printed as-is.
42 * In multiline mode, every [field,value] pair is printed in a line of
43 * its own, thus: "field: value".
44 *
45 * The caller must open a handle for each set of fields to be printed by
46 * invoking ofmt_open(). The invocation to ofmt_open must provide the list of
47 * supported fields, along with formatting information (e.g., field width), and
110 * column, the callback function (*of_cb)() is invoked, and is passed the of_id
111 * value from the ofmt_field_t structure for the field.
112 *
113 * The interpretation of the of_id field is completely private to the caller,
114 * and can be optionally used by the callback function as a cookie
115 * to identify the field being printed when a single callback function is
116 * shared between multiple ofmt_field_t entries.
117 *
118 * The callback function should fill `buf' with the string to be printed for
119 * the field using the data in cbarg.
120 *
121 * The calling application should invoke ofmt_close(ofmt_handle) to free up any
122 * resources allocated for the handle after all printing is completed.
123 *
124 * The printing library computes the current size of the output window when the
125 * handle is first created. If the caller wishes to adjust the window size
126 * after the handle has been created (e.g., on the reception of SIGWINCH by the
127 * caller), the function ofmt_update_winsize(handle) may be called.
128 */
129
130 #include <sys/types.h>
131
132 #ifdef __cplusplus
133 extern "C" {
134 #endif
135
136 /*
137 * Recommended buffer size for buffers passed, for example, to ofmt_strerror().
138 */
139 #define OFMT_BUFSIZE 256
140
141 typedef enum {
142 OFMT_SUCCESS = 0,
143 OFMT_ENOMEM, /* out of memory */
144 OFMT_EBADFIELDS, /* one or more bad fields with good fields */
145 OFMT_ENOFIELDS, /* no valid output fields */
146 OFMT_EPARSEALL, /* 'all' invalid in parsable mode */
147 OFMT_EPARSENONE, /* output fields missing in parsable mode */
148 OFMT_EPARSEWRAP, /* parsable mode incompatible with wrap mode */
149 OFMT_ENOTEMPLATE, /* no template provided for fields */
150 OFMT_EPARSEMULTI /* parsable and multiline don't mix */
151 } ofmt_status_t;
152
153 /*
154 * The callback function for each field is invoked with a pointer to the
155 * ofmt_arg_t structure that contains the <id> registered by the application
170 typedef boolean_t ofmt_cb_t(ofmt_arg_t *, char *, uint_t);
171 typedef struct ofmt_field_s {
172 char *of_name; /* column name */
173 uint_t of_width; /* output column width */
174 uint_t of_id; /* implementation specific cookie */
175 ofmt_cb_t *of_cb; /* callback function defined by caller */
176 } ofmt_field_t;
177
178 /*
179 * ofmt_open() must be called to create the ofmt_handle_t; Resources allocated
180 * for the handle are freed by ofmt_close();
181 */
182 typedef struct ofmt_state_s *ofmt_handle_t;
183 extern ofmt_status_t ofmt_open(const char *, const ofmt_field_t *, uint_t,
184 uint_t, ofmt_handle_t *);
185
186 #define OFMT_PARSABLE 0x00000001 /* machine parsable mode */
187 #define OFMT_WRAP 0x00000002 /* wrap output if field width is exceeded */
188 #define OFMT_MULTILINE 0x00000004 /* "long" output: "name: value" lines */
189 #define OFMT_RIGHTJUST 0x00000008 /* right justified output */
190
191 /*
192 * ofmt_close() must be called to free resources associated
193 * with the ofmt_handle_t
194 */
195 extern void ofmt_close(ofmt_handle_t);
196
197 /*
198 * ofmt_print() emits one row of output
199 */
200 extern void ofmt_print(ofmt_handle_t, void *);
201
202 /*
203 * ofmt_update_winsize() updates the window size information for ofmt_handle_t
204 */
205 extern void ofmt_update_winsize(ofmt_handle_t);
206
207 /*
208 * ofmt_strerror() provides error diagnostics in the buffer that it is passed.
209 */
210 extern char *ofmt_strerror(ofmt_handle_t, ofmt_status_t, char *, uint_t);
211
212 extern void ofmt_check(ofmt_status_t oferr, boolean_t parsable,
213 ofmt_handle_t ofmt,
214 void (*die)(const char *, ...), void (*warn)(const char *, ...));
215
216 #ifdef __cplusplus
217 }
218 #endif
219
220 #endif /* _OFMT_H */
|
8 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
9 * or http://www.opensolaris.org/os/licensing.
10 * See the License for the specific language governing permissions
11 * and limitations under the License.
12 *
13 * When distributing Covered Code, include this CDDL HEADER in each
14 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
15 * If applicable, add the following below this CDDL HEADER, with the
16 * fields enclosed by brackets "[]" replaced with your own identifying
17 * information: Portions Copyright [yyyy] [name of copyright owner]
18 *
19 * CDDL HEADER END
20 */
21
22 /*
23 * Copyright 2010 Sun Microsystems, Inc. All rights reserved.
24 * Use is subject to license terms.
25 */
26
27 /*
28 * Copyright (c) 2015 by Delphix. All rights reserved.
29 * Copyright 2017 Joyent, Inc.
30 */
31
32 #ifndef _OFMT_H
33 #define _OFMT_H
34
35 /*
36 * Data structures and routines for printing output.
37 *
38 * All output is assumed to be in a columnar format, where each column
39 * represents a field to be printed out. Multiple fields in parsable output
40 * are separated by ':', with the ':' character itself escaped by a \
41 * (e.g., IPv6 addresses may be printed as "fe80\:\:1"); single field output
42 * is printed as-is.
43 * In multiline mode, every [field,value] pair is printed in a line of
44 * its own, thus: "field: value".
45 *
46 * The caller must open a handle for each set of fields to be printed by
47 * invoking ofmt_open(). The invocation to ofmt_open must provide the list of
48 * supported fields, along with formatting information (e.g., field width), and
111 * column, the callback function (*of_cb)() is invoked, and is passed the of_id
112 * value from the ofmt_field_t structure for the field.
113 *
114 * The interpretation of the of_id field is completely private to the caller,
115 * and can be optionally used by the callback function as a cookie
116 * to identify the field being printed when a single callback function is
117 * shared between multiple ofmt_field_t entries.
118 *
119 * The callback function should fill `buf' with the string to be printed for
120 * the field using the data in cbarg.
121 *
122 * The calling application should invoke ofmt_close(ofmt_handle) to free up any
123 * resources allocated for the handle after all printing is completed.
124 *
125 * The printing library computes the current size of the output window when the
126 * handle is first created. If the caller wishes to adjust the window size
127 * after the handle has been created (e.g., on the reception of SIGWINCH by the
128 * caller), the function ofmt_update_winsize(handle) may be called.
129 */
130
131 #ifdef __cplusplus
132 extern "C" {
133 #endif
134
135 #include <sys/types.h>
136
137 /*
138 * Recommended buffer size for buffers passed, for example, to ofmt_strerror().
139 */
140 #define OFMT_BUFSIZE 256
141
142 typedef enum {
143 OFMT_SUCCESS = 0,
144 OFMT_ENOMEM, /* out of memory */
145 OFMT_EBADFIELDS, /* one or more bad fields with good fields */
146 OFMT_ENOFIELDS, /* no valid output fields */
147 OFMT_EPARSEALL, /* 'all' invalid in parsable mode */
148 OFMT_EPARSENONE, /* output fields missing in parsable mode */
149 OFMT_EPARSEWRAP, /* parsable mode incompatible with wrap mode */
150 OFMT_ENOTEMPLATE, /* no template provided for fields */
151 OFMT_EPARSEMULTI /* parsable and multiline don't mix */
152 } ofmt_status_t;
153
154 /*
155 * The callback function for each field is invoked with a pointer to the
156 * ofmt_arg_t structure that contains the <id> registered by the application
171 typedef boolean_t ofmt_cb_t(ofmt_arg_t *, char *, uint_t);
172 typedef struct ofmt_field_s {
173 char *of_name; /* column name */
174 uint_t of_width; /* output column width */
175 uint_t of_id; /* implementation specific cookie */
176 ofmt_cb_t *of_cb; /* callback function defined by caller */
177 } ofmt_field_t;
178
179 /*
180 * ofmt_open() must be called to create the ofmt_handle_t; Resources allocated
181 * for the handle are freed by ofmt_close();
182 */
183 typedef struct ofmt_state_s *ofmt_handle_t;
184 extern ofmt_status_t ofmt_open(const char *, const ofmt_field_t *, uint_t,
185 uint_t, ofmt_handle_t *);
186
187 #define OFMT_PARSABLE 0x00000001 /* machine parsable mode */
188 #define OFMT_WRAP 0x00000002 /* wrap output if field width is exceeded */
189 #define OFMT_MULTILINE 0x00000004 /* "long" output: "name: value" lines */
190 #define OFMT_RIGHTJUST 0x00000008 /* right justified output */
191 #define OFMT_NOHEADER 0x00000010 /* do not automatically print header lines */
192
193 /*
194 * ofmt_close() must be called to free resources associated
195 * with the ofmt_handle_t
196 */
197 extern void ofmt_close(ofmt_handle_t);
198
199 /*
200 * Set the field separator used in parsable output (default is ':').
201 */
202 extern void ofmt_set_fs(ofmt_handle_t, char);
203
204 /*
205 * ofmt_print() emits one row of output
206 */
207 extern void ofmt_print(ofmt_handle_t, void *);
208
209 /*
210 * ofmt_print_header() prints the header line. It can be used with
211 * OFMT_NOHEADER to control exactly when the header gets printed.
212 */
213 extern void ofmt_print_header(ofmt_handle_t);
214
215 /*
216 * ofmt_update_winsize() updates the window size information for ofmt_handle_t
217 */
218 extern void ofmt_update_winsize(ofmt_handle_t);
219
220 /*
221 * ofmt_strerror() provides error diagnostics in the buffer that it is passed.
222 */
223 extern char *ofmt_strerror(ofmt_handle_t, ofmt_status_t, char *, uint_t);
224
225 extern void ofmt_check(ofmt_status_t oferr, boolean_t parsable,
226 ofmt_handle_t ofmt,
227 void (*die)(const char *, ...), void (*warn)(const char *, ...));
228
229 #ifdef __cplusplus
230 }
231 #endif
232
233 #endif /* _OFMT_H */
|