OpenSolaris_b135/lib/libinetutil/common/ofmt.h
/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License (the "License").
* You may not use this file except in compliance with the License.
*
* You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
* or http://www.opensolaris.org/os/licensing.
* See the License for the specific language governing permissions
* and limitations under the License.
*
* When distributing Covered Code, include this CDDL HEADER in each
* file and include the License file at usr/src/OPENSOLARIS.LICENSE.
* If applicable, add the following below this CDDL HEADER, with the
* fields enclosed by brackets "[]" replaced with your own identifying
* information: Portions Copyright [yyyy] [name of copyright owner]
*
* CDDL HEADER END
*/
/*
* Copyright 2009 Sun Microsystems, Inc. All rights reserved.
* Use is subject to license terms.
*/
#ifndef _OFMT_H
#define _OFMT_H
/*
* Data structures and routines for printing output.
*
* 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 caller must open a handle for each set of fields to be printed by
* invoking ofmt_open(). The invocation to ofmt_open must provide 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 *ofields[]. The contents of the
* ofmt_field_t structure are used to construct the string that is emitted by
* ofmt_print(), and the interpretation of these contents is described with the
* semantics of ofmt_print() below.
*
* In addition, the call to ofmt_open() should provide a comma-separated
* list of the fields, char *fields_str, that have been selected for output
* (typically the string passed to -o in the command-line). The caller may
* also specify machine-parsable mode by specifying OFMT_PARSABLE in the oflags
* argument. Specifying a null or empty fields_str 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_str set to "all"
* will result in a returned error value of OFMT_EPARSEALL. In human-friendly
* (non machine-parsable) mode, a NULL fields_str, or a value of "all" for
* fields_str, is treated as a request to print all allowable fields that fit
* other applicable constraints.
* To achieve multiline mode, OFMT_MULTILINE needs to be specified in oflags.
* Specifying both OFMT_MULTILINE and OFMT_PARSABLE will result in
* OFMT_EPARSEMULTI.
*
* Thus a typical invocation to open the ofmt_handle would be:
*
* ofmt_handle_t ofmt;
* ofmt_status_t ofmt_err;
*
* ofmt_err = ofmt_open(fields_str, ofields, oflags, maxcols, &ofmt);
*
* where ofields is an array of the form:
*
* static ofmt_field_t ofields[] = {
* {<name>, <field width>, <id>, <callback> },
* :
* {<name>, <field width>, <id>, <callback> },
* {NULL, 0, 0, NULL}}
*
* <callback> is the application-specified function that provides a string
* representation of the value to be printed for the field. The calling
* application may provide unique values of <id> that will be passed back to
* <callback>, allowing a single <callback> to be shared between multiple
* fields in ofields[] with the value of <id> identifying the field that
* triggers the callback.
*
* If successful, ofmt_open() will return OFMT_SUCCESS, with a non-null
* ofmt_handle. The function returns a failure code otherwise, and more
* information about the type of failure can be obtained by calling
* ofmt_strerror()
*
* In order to print a row of output, the calling application should invoke
*
* ofmt_print(ofmt_handle, cbarg);
*
* where 'cbarg' points at the arguments to be passed to the <callback>
* function for each column in the row. The call to ofmt_print() will then
* result in the <callback> function of each selected field from ofields[]
* invoked with cbarg embedded in the ofmt_arg as
*
* (*callback)(ofmt_arg_t *ofmt_arg, char *buf, uint_t bufsize)
*
* Columns selected for output are identified by a match between the of_name
* value in the ofmt_field_t and the fields_str requested. For each selected
* column, the callback function (*of_cb)() is invoked, and is passed the of_id
* value from the ofmt_field_t structure for the field.
*
* 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 ofmt_field_t entries.
*
* The callback function should fill `buf' with the string to be printed for
* the field using the data in cbarg.
*
* The calling application should invoke ofmt_close(ofmt_handle) to free up any
* resources allocated for the handle after all printing is completed.
*
* The printing library computes the current size of the output window when the
* handle is first created. If the caller wishes to adjust the window size
* after the handle has been created (e.g., on the reception of SIGWINCH by the
* caller), the function ofmt_update_winsize(handle) may be called.
*/
#ifdef __cplusplus
extern "C" {
#endif
/*
* Recommended buffer size for buffers passed, for example, to ofmt_strerror().
*/
#define OFMT_BUFSIZE 256
typedef enum {
OFMT_SUCCESS = 0,
OFMT_ENOMEM, /* out of memory */
OFMT_EBADFIELDS, /* one or more bad fields with good fields */
OFMT_ENOFIELDS, /* no valid output fields */
OFMT_EPARSEALL, /* 'all' 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 */
} ofmt_status_t;
/*
* The callback function for each field is invoked with a pointer to the
* ofmt_arg_t structure that contains the <id> registered by the application
* for that field, and the cbarg used by the application when invoking
* ofmt_output().
*/
typedef struct ofmt_arg_s {
uint_t ofmt_id;
void *ofmt_cbarg;
} ofmt_arg_t;
/*
* ofmt callback function that provides a string representation of the value to
* be printed for the field.
*/
typedef boolean_t ofmt_cb_t(ofmt_arg_t *, char *, uint_t);
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;
/*
* ofmt_open() must be called to create the ofmt_handle_t; Resources allocated
* for the handle are freed by ofmt_close();
*/
typedef struct ofmt_state_s *ofmt_handle_t;
extern ofmt_status_t ofmt_open(const char *, const ofmt_field_t *, uint_t,
uint_t, ofmt_handle_t *);
#define OFMT_PARSABLE 0x00000001 /* machine parsable mode */
#define OFMT_WRAP 0x00000002 /* wrap output if field width is exceeded */
#define OFMT_MULTILINE 0x00000004 /* "long" output: "name: value" lines */
/*
* ofmt_close() must be called to free resources associated
* with the ofmt_handle_t
*/
extern void ofmt_close(ofmt_handle_t);
/*
* ofmt_print() emits one row of output
*/
extern void ofmt_print(ofmt_handle_t, void *);
/*
* ofmt_update_winsize() updates the window size information for ofmt_handle_t
*/
extern void ofmt_update_winsize(ofmt_handle_t);
/*
* ofmt_strerror() provides error diagnostics in the buffer that it is passed.
*/
extern char *ofmt_strerror(ofmt_handle_t, ofmt_status_t, char *, uint_t);
#ifdef __cplusplus
}
#endif
#endif /* _OFMT_H */