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