OFMT(3OFMT) | Formatted Output Functions | OFMT(3OFMT) |
ofmt_open
,
ofmt_print
,
ofmt_print_header
,
ofmt_update_winsize
,
ofmt_set_fs
, ofmt_strerror
,
ofmt_close
— data structures
and routines for printing output
Formatted output library (libofmt, -lofmt)
#include
<ofmt.h>
ofmt_status_t
ofmt_open
(const char *fields,
const ofmt_field_t *template, uint_t
flags, uint_t maxcols,
ofmt_handle_t *ofmt);
void
ofmt_print
(ofmt_handle_t ofmt,
void *cbarg);
void
ofmt_print_header
(ofmt_handle_t
ofmt);
void
ofmt_update_winsize
(ofmt_handle_t
ofmt);
void
ofmt_set_fs
(ofmt_handle_t ofmt,
char fs);
char *
ofmt_strerror
(ofmt_handle_t
ofmt, ofmt_status_t error, char
*buf, uint_t bufsize);
void
ofmt_close
(ofmt_handle_t
ofmt);
The libofmt
library provides data
structures and routines for printing output.
Currently this is an internal interface. The interface can and will change without notice as the project needs, at any time.
All output is assumed to be in a columnar format, where each column represents a field to be printed out. Multiple fields in parsable output are separated by ‘:’, with the ‘:’ character itself escaped by a ‘\’ (e.g., IPv6 addresses may be printed as "fe80\:\:1"); single field output is printed as-is. In multiline mode, every [field,value] pair is printed in a line of its own, thus: "field: value".
The ofmt_field_t data structure used in ofmt_open is defined as follows:
typedef struct ofmt_field_s { char *of_name; /* column name */ uint_t of_width; /* output column width */ uint_t of_id; /* implementation specific cookie */ ofmt_cb_t *of_cb; /* callback function defined by caller */ } ofmt_field_t;
The ofmt_arg_t data structure which is passed to callback function is defined as follows:
typedef struct ofmt_arg_s { uint_t ofmt_id; /* implementation specific cookie */ uint_t ofmt_width; /* output column width */ uint_t ofmt_index; /* unused */ void *ofmt_cbarg; /* argument passed to ofmt_print() */ } ofmt_arg_t;
ofmt_open
()The ofmt_open
() function opens a handle
returned in ofmt for each set of fields to be
printed.
fields is a comma-separated list of the
fields that have been selected for output (typically the string passed to
-o
in the command-line). Columns selected for output
are identified by a match between the of_name value in
the template and the fields
requested. In human-friendly (non machine-parsable) mode,
NULL
fields, or a value of
"all" is treated as a request to print all allowable fields that
fit other applicable constraints.
template specifies the list of supported
fields, along with formatting information (e.g., field width), and a pointer
to a callback function that can provide a string representation of the value
to be printed out. The set of supported fields must be a
NULL
terminated array of type
ofmt_field_t, described in
Data Structures, as follows:
{<of_name>, <of_width>, <of_id>, <of_cb> }, ... {<of_name>, <of_width>, <of_id>, <of_cb> }, {NULL, 0, 0, NULL}
of_cb is the application-specified callback function with the following prototype that provides a string representation of the value to be printed for the field:
boolean_t (*of_cb)(ofmt_arg_t *ofmt_arg, char *buf, uint_t bufsize)
The callback must not write beyond bufsize
bytes of the string form into buf. If the function
successfully translates the field into its string representation and places
it into buf, then the callback function should return
B_TRUE
. Otherwise, the callback function should
return B_FALSE
.
The interpretation of the of_id field is completely private to the caller, and can be optionally used by the callback function as a cookie to identify the field being printed when a single callback function is shared between multiple template entries.
The flags can be any valid combination of the following:
OFMT_PARSABLE
OFMT_EPARSENONE
. An
attempt to create a handle in machine-parsable mode with the
fields set to "all" will result in a
returned error value of OFMT_EPARSEALL
.OFMT_WRAP
OFMT_MULTILINE
OFMT_MULTILINE
and
OFMT_PARSABLE
will result in
OFMT_EPARSEMULTI
.OFMT_RIGHTJUST
OFMT_NOHEADER
ofmt_print
().The non-zero maxcols limits the number of output columns.
ofmt_print
()The ofmt_print
() function prints a row of
output.
cbarg points at the
arguments to be passed to the callback function for each column in the row.
The call to
ofmt_print
()
will result in the callback function of each selected field invoked with
of_id, of_width and
cbarg embedded in ofmt_arg,
described in Data Structures.
The callback function should fill buf with the string to be printed for the field using the data in cbarg.
ofmt_print_header
()The ofmt_print_header
() function prints
the output header. This is usually done as part of calling
ofmt_print
(), but is skipped when using
OFMT_NOHEADER
. This function allows you to insert it
when and where desired.
ofmt_update_winsize
()The ofmt_update_winsize
() function updates
the window size information (which is initially computed when the handle is
created) in the ofmt. If the
TIOCGWINSZ
ioctl fails, the window size is set to
80x24.
ofmt_set_fs
()The ofmt_set_fs
() function sets the output
field separator for parsable output.
ofmt_strerror
()The ofmt_strerror
() function returns error
diagnostics in buf using the information in the
ofmt and error.
Using a buf size of
OFMT_BUFSIZE
is recommended.
ofmt_close
()The ofmt_close
() function frees any
resources allocated for the handle after printing is completed.
If successful, the ofmt_open
() function
will return OFMT_SUCCESS
, with a non-null
ofmt_handle. The function returns one of the failure
codes (enumerated in ofmt_status_t) listed below
otherwise:
OFMT_ENOMEM
OFMT_EBADFIELDS
OFMT_ENOFIELDS
OFMT_EPARSEALL
OFMT_EPARSENONE
OFMT_EPARSEWRAP
OFMT_ENOTEMPLATE
OFMT_EPARSEMULTI
More information about the type of failure can be obtained by
calling ofmt_strerror
().
The ofmt_strerror
() function returns the
buf.
February 13, 2019 | OmniOS |