8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * CDDL HEADER START
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * The contents of this file are subject to the terms of the
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * Common Development and Distribution License (the "License").
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * You may not use this file except in compliance with the License.
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * or http://www.opensolaris.org/os/licensing.
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * See the License for the specific language governing permissions
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * and limitations under the License.
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * When distributing Covered Code, include this CDDL HEADER in each
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * If applicable, add the following below this CDDL HEADER, with the
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * fields enclosed by brackets "[]" replaced with your own identifying
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * information: Portions Copyright [yyyy] [name of copyright owner]
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * CDDL HEADER END
0dc2366f7b9f9f36e10909b1e95edbf2a261c2acVenugopal Iyer * Copyright 2010 Sun Microsystems, Inc. All rights reserved.
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * Use is subject to license terms.
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * Data structures and routines for printing output.
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * All output is assumed to be in a columnar format, where each column
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * represents a field to be printed out. Multiple fields in parsable output
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * are separated by ':', with the ':' character itself escaped by a \
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * (e.g., IPv6 addresses may be printed as "fe80\:\:1"); single field output
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * is printed as-is.
dbed73cbda2229fd1aa6dc5743993cae7f0a7ee9Sangeeta Misra * In multiline mode, every [field,value] pair is printed in a line of
dbed73cbda2229fd1aa6dc5743993cae7f0a7ee9Sangeeta Misra * its own, thus: "field: value".
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * The caller must open a handle for each set of fields to be printed by
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * invoking ofmt_open(). The invocation to ofmt_open must provide the list of
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * supported fields, along with formatting information (e.g., field width), and
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * a pointer to a callback function that can provide a string representation of
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * the value to be printed out. The set of supported fields must be a NULL
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * terminated array of type ofmt_field_t *ofields[]. The contents of the
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * ofmt_field_t structure are used to construct the string that is emitted by
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * ofmt_print(), and the interpretation of these contents is described with the
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * semantics of ofmt_print() below.
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * In addition, the call to ofmt_open() should provide a comma-separated
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * list of the fields, char *fields_str, that have been selected for output
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * (typically the string passed to -o in the command-line). The caller may
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * also specify machine-parsable mode by specifying OFMT_PARSABLE in the oflags
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * argument. Specifying a null or empty fields_str in the machine-parsable mode
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * will result in a returned error value of OFMT_EPARSENONE. An attempt to
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * create a handle in machine-parsable mode with the fields_str set to "all"
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * will result in a returned error value of OFMT_EPARSEALL. In human-friendly
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * (non machine-parsable) mode, a NULL fields_str, or a value of "all" for
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * fields_str, is treated as a request to print all allowable fields that fit
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * other applicable constraints.
dbed73cbda2229fd1aa6dc5743993cae7f0a7ee9Sangeeta Misra * To achieve multiline mode, OFMT_MULTILINE needs to be specified in oflags.
dbed73cbda2229fd1aa6dc5743993cae7f0a7ee9Sangeeta Misra * Specifying both OFMT_MULTILINE and OFMT_PARSABLE will result in
dbed73cbda2229fd1aa6dc5743993cae7f0a7ee9Sangeeta Misra * OFMT_EPARSEMULTI.
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * Thus a typical invocation to open the ofmt_handle would be:
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * ofmt_handle_t ofmt;
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * ofmt_status_t ofmt_err;
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * ofmt_err = ofmt_open(fields_str, ofields, oflags, maxcols, &ofmt);
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * where ofields is an array of the form:
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * static ofmt_field_t ofields[] = {
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * {<name>, <field width>, <id>, <callback> },
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * {<name>, <field width>, <id>, <callback> },
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * {NULL, 0, 0, NULL}}
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * <callback> is the application-specified function that provides a string
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * representation of the value to be printed for the field. The calling
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * application may provide unique values of <id> that will be passed back to
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * <callback>, allowing a single <callback> to be shared between multiple
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * fields in ofields[] with the value of <id> identifying the field that
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * triggers the callback.
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * If successful, ofmt_open() will return OFMT_SUCCESS, with a non-null
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * ofmt_handle. The function returns a failure code otherwise, and more
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * information about the type of failure can be obtained by calling
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * ofmt_strerror()
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * In order to print a row of output, the calling application should invoke
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * ofmt_print(ofmt_handle, cbarg);
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * where 'cbarg' points at the arguments to be passed to the <callback>
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * function for each column in the row. The call to ofmt_print() will then
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * result in the <callback> function of each selected field from ofields[]
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * invoked with cbarg embedded in the ofmt_arg as
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * (*callback)(ofmt_arg_t *ofmt_arg, char *buf, uint_t bufsize)
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * Columns selected for output are identified by a match between the of_name
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * value in the ofmt_field_t and the fields_str requested. For each selected
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * column, the callback function (*of_cb)() is invoked, and is passed the of_id
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * value from the ofmt_field_t structure for the field.
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * The interpretation of the of_id field is completely private to the caller,
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * and can be optionally used by the callback function as a cookie
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * to identify the field being printed when a single callback function is
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * shared between multiple ofmt_field_t entries.
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * The callback function should fill `buf' with the string to be printed for
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * the field using the data in cbarg.
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * The calling application should invoke ofmt_close(ofmt_handle) to free up any
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * resources allocated for the handle after all printing is completed.
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * The printing library computes the current size of the output window when the
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * handle is first created. If the caller wishes to adjust the window size
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * after the handle has been created (e.g., on the reception of SIGWINCH by the
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * caller), the function ofmt_update_winsize(handle) may be called.
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * Recommended buffer size for buffers passed, for example, to ofmt_strerror().
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhantypedef enum {
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan OFMT_EBADFIELDS, /* one or more bad fields with good fields */
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan OFMT_ENOFIELDS, /* no valid output fields */
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan OFMT_EPARSEALL, /* 'all' invalid in parsable mode */
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan OFMT_EPARSENONE, /* output fields missing in parsable mode */
25ec3e3dd27cc1038c10efa18ed08f064eab5fbeEric Cheng OFMT_EPARSEWRAP, /* parsable mode incompatible with wrap mode */
dbed73cbda2229fd1aa6dc5743993cae7f0a7ee9Sangeeta Misra OFMT_ENOTEMPLATE, /* no template provided for fields */
dbed73cbda2229fd1aa6dc5743993cae7f0a7ee9Sangeeta Misra OFMT_EPARSEMULTI /* parsable and multiline don't mix */
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * The callback function for each field is invoked with a pointer to the
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * ofmt_arg_t structure that contains the <id> registered by the application
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * for that field, and the cbarg used by the application when invoking
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * ofmt_output().
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * ofmt callback function that provides a string representation of the value to
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * be printed for the field.
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhantypedef boolean_t ofmt_cb_t(ofmt_arg_t *, char *, uint_t);
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan uint_t of_id; /* implementation specific cookie */
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan ofmt_cb_t *of_cb; /* callback function defined by caller */
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * ofmt_open() must be called to create the ofmt_handle_t; Resources allocated
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * for the handle are freed by ofmt_close();
2b24ab6b3865caeede9eeb9db6b83e1d89dcd1eaSebastien Royextern ofmt_status_t ofmt_open(const char *, const ofmt_field_t *, uint_t,
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan#define OFMT_PARSABLE 0x00000001 /* machine parsable mode */
25ec3e3dd27cc1038c10efa18ed08f064eab5fbeEric Cheng#define OFMT_WRAP 0x00000002 /* wrap output if field width is exceeded */
dbed73cbda2229fd1aa6dc5743993cae7f0a7ee9Sangeeta Misra#define OFMT_MULTILINE 0x00000004 /* "long" output: "name: value" lines */
0dc2366f7b9f9f36e10909b1e95edbf2a261c2acVenugopal Iyer#define OFMT_RIGHTJUST 0x00000008 /* right justified output */
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * ofmt_close() must be called to free resources associated
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * with the ofmt_handle_t
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * ofmt_print() emits one row of output
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhanextern void ofmt_print(ofmt_handle_t, void *);
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * ofmt_update_winsize() updates the window size information for ofmt_handle_t
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhanextern void ofmt_update_winsize(ofmt_handle_t);
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan * ofmt_strerror() provides error diagnostics in the buffer that it is passed.
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhanextern char *ofmt_strerror(ofmt_handle_t, ofmt_status_t, char *, uint_t);
8002d4117c1ea26aff1f16f584ae97bdbd5b21d5Sowmini Varadhan#endif /* _OFMT_H */