OFMT(3OFMT) Formatted Output Functions OFMT(3OFMT)

NAME


ofmt_open, ofmt_print, ofmt_print_header, ofmt_update_winsize, ofmt_set_fs,
ofmt_strerror, ofmt_close - data structures and routines for printing
output

LIBRARY


Formatted output library (libofmt, -lofmt)

SYNOPSIS


#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);

DESCRIPTION


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".

Data Structures


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 Machine-parsable mode. Specifying a null or empty fields
in the machine-parsable mode will result in a returned
error value of 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 Wrap output if field width is exceeded. Currently output
is wrapped at whitespace or comma characters.
OFMT_MULTILINE Multiline mode. Specifying both OFMT_MULTILINE and
OFMT_PARSABLE will result in OFMT_EPARSEMULTI.
OFMT_RIGHTJUST Right justified output.
OFMT_NOHEADER Skip printing the header when calling 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.

RETURN VALUES


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 out of memory
OFMT_EBADFIELDS one or more bad fields with good fields
OFMT_ENOFIELDS no valid output fields
OFMT_EPARSEALL "all" is invalid in parsable mode
OFMT_EPARSENONE output fields missing in parsable mode
OFMT_EPARSEWRAP parsable mode incompatible with wrap mode
OFMT_ENOTEMPLATE no template provided for fields
OFMT_EPARSEMULTI parsable and multiline don't mix

More information about the type of failure can be obtained by calling
ofmt_strerror().

The ofmt_strerror() function returns the buf.

INTERFACE STABILITY


Private.

SEE ALSO


ioctl(2), strerror(3C), attributes(5)

OmniOS February 13, 2019 OmniOS