1 OFMT(3OFMT) Formatted Output Functions OFMT(3OFMT)
2
3 NAME
4 ofmt_open, ofmt_print, ofmt_update_winsize, ofmt_strerror, ofmt_close -
5 data structures and routines for printing output
6
7 LIBRARY
8 Formatted output library (libofmt, -lofmt)
9
10 SYNOPSIS
11 #include <ofmt.h>
12
13 ofmt_status_t
14 ofmt_open(const char *fields, const ofmt_field_t *template, uint_t flags,
15 uint_t maxcols, ofmt_handle_t *ofmt);
16
17 void
18 ofmt_print(ofmt_handle_t ofmt, void *cbarg);
19
20 void
21 ofmt_update_winsize(ofmt_handle_t ofmt);
22
23 char *
24 ofmt_strerror(ofmt_handle_t ofmt, ofmt_status_t error, char *buf,
25 uint_t bufsize);
26
27 void
28 ofmt_close(ofmt_handle_t ofmt);
29
30 DESCRIPTION
31 The libofmt library provides data structures and routines for printing
32 output.
33
34 Currently this is an internal interface. The interface can and will
35 change without notice as the project needs, at any time.
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. In multiline mode, every [field,value] pair is printed
42 in a line of its own, thus: "field: value".
96 return B_TRUE. Otherwise, the callback function should return B_FALSE.
97
98 The interpretation of the of_id field is completely private to the
99 caller, and can be optionally used by the callback function as a cookie
100 to identify the field being printed when a single callback function is
101 shared between multiple template entries.
102
103 The flags can be any valid combination of the following:
104
105 OFMT_PARSABLE Machine-parsable mode. Specifying a null or empty fields
106 in the machine-parsable mode will result in a returned
107 error value of OFMT_EPARSENONE. An attempt to create a
108 handle in machine-parsable mode with the fields set to
109 "all" will result in a returned error value of
110 OFMT_EPARSEALL.
111 OFMT_WRAP Wrap output if field width is exceeded. Currently output
112 is wrapped at whitespace or comma characters.
113 OFMT_MULTILINE Multiline mode. Specifying both OFMT_MULTILINE and
114 OFMT_PARSABLE will result in OFMT_EPARSEMULTI.
115 OFMT_RIGHTJUST Right justified output.
116
117 The non-zero maxcols limits the number of output columns.
118
119 ofmt_print()
120 The ofmt_print() function prints a row of output.
121
122 cbarg points at the arguments to be passed to the callback function for
123 each column in the row. The call to ofmt_print() will result in the
124 callback function of each selected field invoked with of_id, of_width and
125 cbarg embedded in ofmt_arg, described in Data Structures.
126
127 The callback function should fill buf with the string to be printed for
128 the field using the data in cbarg.
129
130 ofmt_update_winsize()
131 The ofmt_update_winsize() function updates the window size information
132 (which is initially computed when the handle is created) in the ofmt. If
133 the TIOCGWINSZ ioctl fails, the window size is set to 80x24.
134
135 ofmt_strerror()
136 The ofmt_strerror() function returns error diagnostics in buf using the
137 information in the ofmt and error.
138
139 Using a buf size of OFMT_BUFSIZE is recommended.
140
141 ofmt_close()
142 The ofmt_close() function frees any resources allocated for the handle
143 after printing is completed.
144
145 RETURN VALUES
146 If successful, the ofmt_open() function will return OFMT_SUCCESS, with a
147 non-null ofmt_handle. The function returns one of the failure codes
148 (enumerated in ofmt_status_t) listed below otherwise:
149
150 OFMT_ENOMEM out of memory
151 OFMT_EBADFIELDS one or more bad fields with good fields
152 OFMT_ENOFIELDS no valid output fields
153 OFMT_EPARSEALL "all" is invalid in parsable mode
154 OFMT_EPARSENONE output fields missing in parsable mode
155 OFMT_EPARSEWRAP parsable mode incompatible with wrap mode
156 OFMT_ENOTEMPLATE no template provided for fields
157 OFMT_EPARSEMULTI parsable and multiline don't mix
158
159 More information about the type of failure can be obtained by calling
160 ofmt_strerror().
161
162 The ofmt_strerror() function returns the buf.
163
164 INTERFACE STABILITY
165 Private.
166
167 SEE ALSO
168 ioctl(2), strerror(3C), attributes(5)
169
170 illumos December 20, 2018 illumos
|
1 OFMT(3OFMT) Formatted Output Functions OFMT(3OFMT)
2
3 NAME
4 ofmt_open, ofmt_print, ofmt_print_header, ofmt_update_winsize,
5 ofmt_set_fs, ofmt_strerror, ofmt_close - data structures and routines for
6 printing output
7
8 LIBRARY
9 Formatted output library (libofmt, -lofmt)
10
11 SYNOPSIS
12 #include <ofmt.h>
13
14 ofmt_status_t
15 ofmt_open(const char *fields, const ofmt_field_t *template, uint_t flags,
16 uint_t maxcols, ofmt_handle_t *ofmt);
17
18 void
19 ofmt_print(ofmt_handle_t ofmt, void *cbarg);
20
21 void
22 ofmt_print_header(ofmt_handle_t ofmt);
23
24 void
25 ofmt_update_winsize(ofmt_handle_t ofmt);
26
27 void
28 ofmt_set_fs(ofmt_handle_t ofmt, char fs);
29
30 char *
31 ofmt_strerror(ofmt_handle_t ofmt, ofmt_status_t error, char *buf,
32 uint_t bufsize);
33
34 void
35 ofmt_close(ofmt_handle_t ofmt);
36
37 DESCRIPTION
38 The libofmt library provides data structures and routines for printing
39 output.
40
41 Currently this is an internal interface. The interface can and will
42 change without notice as the project needs, at any time.
43
44 All output is assumed to be in a columnar format, where each column
45 represents a field to be printed out. Multiple fields in parsable output
46 are separated by `:', with the `:' character itself escaped by a `\'
47 (e.g., IPv6 addresses may be printed as "fe80\:\:1"); single field output
48 is printed as-is. In multiline mode, every [field,value] pair is printed
49 in a line of its own, thus: "field: value".
103 return B_TRUE. Otherwise, the callback function should return B_FALSE.
104
105 The interpretation of the of_id field is completely private to the
106 caller, and can be optionally used by the callback function as a cookie
107 to identify the field being printed when a single callback function is
108 shared between multiple template entries.
109
110 The flags can be any valid combination of the following:
111
112 OFMT_PARSABLE Machine-parsable mode. Specifying a null or empty fields
113 in the machine-parsable mode will result in a returned
114 error value of OFMT_EPARSENONE. An attempt to create a
115 handle in machine-parsable mode with the fields set to
116 "all" will result in a returned error value of
117 OFMT_EPARSEALL.
118 OFMT_WRAP Wrap output if field width is exceeded. Currently output
119 is wrapped at whitespace or comma characters.
120 OFMT_MULTILINE Multiline mode. Specifying both OFMT_MULTILINE and
121 OFMT_PARSABLE will result in OFMT_EPARSEMULTI.
122 OFMT_RIGHTJUST Right justified output.
123 OFMT_NOHEADER Skip printing the header when calling ofmt_print().
124
125 The non-zero maxcols limits the number of output columns.
126
127 ofmt_print()
128 The ofmt_print() function prints a row of output.
129
130 cbarg points at the arguments to be passed to the callback function for
131 each column in the row. The call to ofmt_print() will result in the
132 callback function of each selected field invoked with of_id, of_width and
133 cbarg embedded in ofmt_arg, described in Data Structures.
134
135 The callback function should fill buf with the string to be printed for
136 the field using the data in cbarg.
137
138 ofmt_print_header()
139 The ofmt_print_header() function prints the output header. This is
140 usually done as part of calling ofmt_print(), but is skipped when using
141 OFMT_NOHEADER. This function allows you to insert it when and where
142 desired.
143
144 ofmt_update_winsize()
145 The ofmt_update_winsize() function updates the window size information
146 (which is initially computed when the handle is created) in the ofmt. If
147 the TIOCGWINSZ ioctl fails, the window size is set to 80x24.
148
149 ofmt_set_fs()
150 The ofmt_set_fs() function sets the output field separator for parsable
151 output.
152
153 ofmt_strerror()
154 The ofmt_strerror() function returns error diagnostics in buf using the
155 information in the ofmt and error.
156
157 Using a buf size of OFMT_BUFSIZE is recommended.
158
159 ofmt_close()
160 The ofmt_close() function frees any resources allocated for the handle
161 after printing is completed.
162
163 RETURN VALUES
164 If successful, the ofmt_open() function will return OFMT_SUCCESS, with a
165 non-null ofmt_handle. The function returns one of the failure codes
166 (enumerated in ofmt_status_t) listed below otherwise:
167
168 OFMT_ENOMEM out of memory
169 OFMT_EBADFIELDS one or more bad fields with good fields
170 OFMT_ENOFIELDS no valid output fields
171 OFMT_EPARSEALL "all" is invalid in parsable mode
172 OFMT_EPARSENONE output fields missing in parsable mode
173 OFMT_EPARSEWRAP parsable mode incompatible with wrap mode
174 OFMT_ENOTEMPLATE no template provided for fields
175 OFMT_EPARSEMULTI parsable and multiline don't mix
176
177 More information about the type of failure can be obtained by calling
178 ofmt_strerror().
179
180 The ofmt_strerror() function returns the buf.
181
182 INTERFACE STABILITY
183 Private.
184
185 SEE ALSO
186 ioctl(2), strerror(3C), attributes(5)
187
188 illumos February 13, 2019 illumos
|