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