/* * 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[] = { * {, , , }, * : * {, , , }, * {NULL, 0, 0, NULL}} * * 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 that will be passed back to * , allowing a single to be shared between multiple * fields in ofields[] with the value of 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 * function for each column in the row. The call to ofmt_print() will then * result in the 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 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 */