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.man.txt
+++ new/usr/src/man/man3ofmt/ofmt.3ofmt.man.txt
1 1 OFMT(3OFMT) Formatted Output Functions OFMT(3OFMT)
2 2
3 3 NAME
4 - ofmt_open, ofmt_print, ofmt_update_winsize, ofmt_strerror, ofmt_close -
5 - data structures and routines for printing output
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
6 7
7 8 LIBRARY
8 9 Formatted output library (libofmt, -lofmt)
9 10
10 11 SYNOPSIS
11 12 #include <ofmt.h>
12 13
13 14 ofmt_status_t
14 15 ofmt_open(const char *fields, const ofmt_field_t *template, uint_t flags,
15 16 uint_t maxcols, ofmt_handle_t *ofmt);
16 17
17 18 void
18 19 ofmt_print(ofmt_handle_t ofmt, void *cbarg);
19 20
20 21 void
22 + ofmt_print_header(ofmt_handle_t ofmt);
23 +
24 + void
21 25 ofmt_update_winsize(ofmt_handle_t ofmt);
22 26
27 + void
28 + ofmt_set_fs(ofmt_handle_t ofmt, char fs);
29 +
23 30 char *
24 31 ofmt_strerror(ofmt_handle_t ofmt, ofmt_status_t error, char *buf,
25 32 uint_t bufsize);
26 33
27 34 void
28 35 ofmt_close(ofmt_handle_t ofmt);
29 36
30 37 DESCRIPTION
31 38 The libofmt library provides data structures and routines for printing
32 39 output.
33 40
34 41 Currently this is an internal interface. The interface can and will
35 42 change without notice as the project needs, at any time.
36 43
37 44 All output is assumed to be in a columnar format, where each column
38 45 represents a field to be printed out. Multiple fields in parsable output
39 46 are separated by `:', with the `:' character itself escaped by a `\'
40 47 (e.g., IPv6 addresses may be printed as "fe80\:\:1"); single field output
41 48 is printed as-is. In multiline mode, every [field,value] pair is printed
42 49 in a line of its own, thus: "field: value".
43 50
44 51 Data Structures
45 52 The ofmt_field_t data structure used in ofmt_open is defined as follows:
46 53
47 54 typedef struct ofmt_field_s {
48 55 char *of_name; /* column name */
49 56 uint_t of_width; /* output column width */
50 57 uint_t of_id; /* implementation specific cookie */
51 58 ofmt_cb_t *of_cb; /* callback function defined by caller */
52 59 } ofmt_field_t;
53 60
54 61 The ofmt_arg_t data structure which is passed to callback function is
55 62 defined as follows:
56 63
57 64 typedef struct ofmt_arg_s {
58 65 uint_t ofmt_id; /* implementation specific cookie */
59 66 uint_t ofmt_width; /* output column width */
60 67 uint_t ofmt_index; /* unused */
61 68 void *ofmt_cbarg; /* argument passed to ofmt_print() */
62 69 } ofmt_arg_t;
63 70
64 71 ofmt_open()
65 72 The ofmt_open() function opens a handle returned in ofmt for each set of
66 73 fields to be printed.
67 74
68 75 fields is a comma-separated list of the fields that have been selected
69 76 for output (typically the string passed to -o in the command-line).
70 77 Columns selected for output are identified by a match between the of_name
71 78 value in the template and the fields requested. In human-friendly (non
72 79 machine-parsable) mode, NULL fields, or a value of "all" is treated as a
73 80 request to print all allowable fields that fit other applicable
74 81 constraints.
75 82
76 83 template specifies the list of supported fields, along with formatting
77 84 information (e.g., field width), and a pointer to a callback function
78 85 that can provide a string representation of the value to be printed out.
79 86 The set of supported fields must be a NULL terminated array of type
80 87 ofmt_field_t, described in Data Structures, as follows:
81 88
82 89 {<of_name>, <of_width>, <of_id>, <of_cb> },
83 90 ...
84 91 {<of_name>, <of_width>, <of_id>, <of_cb> },
85 92 {NULL, 0, 0, NULL}
86 93
87 94 of_cb is the application-specified callback function with the following
88 95 prototype that provides a string representation of the value to be
89 96 printed for the field:
90 97
91 98 boolean_t (*of_cb)(ofmt_arg_t *ofmt_arg, char *buf, uint_t bufsize)
92 99
93 100 The callback must not write beyond bufsize bytes of the string form into
94 101 buf. If the function successfully translates the field into its string
95 102 representation and places it into buf, then the callback function should
96 103 return B_TRUE. Otherwise, the callback function should return B_FALSE.
97 104
98 105 The interpretation of the of_id field is completely private to the
99 106 caller, and can be optionally used by the callback function as a cookie
100 107 to identify the field being printed when a single callback function is
101 108 shared between multiple template entries.
102 109
103 110 The flags can be any valid combination of the following:
104 111
105 112 OFMT_PARSABLE Machine-parsable mode. Specifying a null or empty fields
|
↓ open down ↓ |
73 lines elided |
↑ open up ↑ |
106 113 in the machine-parsable mode will result in a returned
107 114 error value of OFMT_EPARSENONE. An attempt to create a
108 115 handle in machine-parsable mode with the fields set to
109 116 "all" will result in a returned error value of
110 117 OFMT_EPARSEALL.
111 118 OFMT_WRAP Wrap output if field width is exceeded. Currently output
112 119 is wrapped at whitespace or comma characters.
113 120 OFMT_MULTILINE Multiline mode. Specifying both OFMT_MULTILINE and
114 121 OFMT_PARSABLE will result in OFMT_EPARSEMULTI.
115 122 OFMT_RIGHTJUST Right justified output.
123 + OFMT_NOHEADER Skip printing the header when calling ofmt_print().
116 124
117 125 The non-zero maxcols limits the number of output columns.
118 126
119 127 ofmt_print()
120 128 The ofmt_print() function prints a row of output.
121 129
122 130 cbarg points at the arguments to be passed to the callback function for
123 131 each column in the row. The call to ofmt_print() will result in the
124 132 callback function of each selected field invoked with of_id, of_width and
125 133 cbarg embedded in ofmt_arg, described in Data Structures.
126 134
127 135 The callback function should fill buf with the string to be printed for
128 136 the field using the data in cbarg.
129 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 +
130 144 ofmt_update_winsize()
131 145 The ofmt_update_winsize() function updates the window size information
132 146 (which is initially computed when the handle is created) in the ofmt. If
133 147 the TIOCGWINSZ ioctl fails, the window size is set to 80x24.
134 148
149 + ofmt_set_fs()
150 + The ofmt_set_fs() function sets the output field separator for parsable
151 + output.
152 +
135 153 ofmt_strerror()
136 154 The ofmt_strerror() function returns error diagnostics in buf using the
137 155 information in the ofmt and error.
138 156
139 157 Using a buf size of OFMT_BUFSIZE is recommended.
140 158
141 159 ofmt_close()
142 160 The ofmt_close() function frees any resources allocated for the handle
143 161 after printing is completed.
144 162
145 163 RETURN VALUES
146 164 If successful, the ofmt_open() function will return OFMT_SUCCESS, with a
147 165 non-null ofmt_handle. The function returns one of the failure codes
148 166 (enumerated in ofmt_status_t) listed below otherwise:
149 167
150 168 OFMT_ENOMEM out of memory
151 169 OFMT_EBADFIELDS one or more bad fields with good fields
152 170 OFMT_ENOFIELDS no valid output fields
153 171 OFMT_EPARSEALL "all" is invalid in parsable mode
154 172 OFMT_EPARSENONE output fields missing in parsable mode
155 173 OFMT_EPARSEWRAP parsable mode incompatible with wrap mode
156 174 OFMT_ENOTEMPLATE no template provided for fields
157 175 OFMT_EPARSEMULTI parsable and multiline don't mix
158 176
159 177 More information about the type of failure can be obtained by calling
|
↓ open down ↓ |
15 lines elided |
↑ open up ↑ |
160 178 ofmt_strerror().
161 179
162 180 The ofmt_strerror() function returns the buf.
163 181
164 182 INTERFACE STABILITY
165 183 Private.
166 184
167 185 SEE ALSO
168 186 ioctl(2), strerror(3C), attributes(5)
169 187
170 -illumos December 20, 2018 illumos
188 +illumos February 13, 2019 illumos
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX