diff options
Diffstat (limited to 'usr/src/lib/libinetutil/common/ofmt.h')
| -rw-r--r-- | usr/src/lib/libinetutil/common/ofmt.h | 198 |
1 files changed, 198 insertions, 0 deletions
diff --git a/usr/src/lib/libinetutil/common/ofmt.h b/usr/src/lib/libinetutil/common/ofmt.h new file mode 100644 index 0000000000..ff03b80ae0 --- /dev/null +++ b/usr/src/lib/libinetutil/common/ofmt.h @@ -0,0 +1,198 @@ +/* + * 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. + * + * 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. + * + * 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_ENOTEMPLATE /* no template provided for fields */ +} 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 *, ofmt_field_t *, uint_t, + uint_t, ofmt_handle_t *); + +#define OFMT_PARSABLE 0x00000001 /* machine parsable mode */ + +/* + * 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 */ |