6782154 one copy of parse_output_fields() & friends is enough.

6751617 dladm show-link -s -i needs to flush stdout after each line
6687693 dladm show-aggr -s -i 1 in nv shows the column header only once per invocation

6 files changed, 704 insertions, 12 deletions

diff --git a/usr/src/lib/libinetutil/Makefile b/usr/src/lib/libinetutil/Makefile
index 980894ba78..0bc13a5c87 100644
--- a/usr/src/lib/libinetutil/Makefile
+++ b/usr/src/lib/libinetutil/Makefile
@@ -19,19 +19,22 @@
 # CDDL HEADER END
 #
 #
-# Copyright 2006 Sun Microsystems, Inc.  All rights reserved.
+# Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
 # Use is subject to license terms.
 #
-# ident	"%Z%%M%	%I%	%E% SMI"
 #
 
 include ../Makefile.lib
 
-HDRS =		libinetutil.h
+HDRS =		libinetutil.h ofmt.h
 HDRDIR =	common
 SUBDIRS	=	$(MACH)
 $(BUILD64)SUBDIRS += $(MACH64)
 
+POFILE =	libinetutil.po
+MSGFILES =	common/ofmt.c
+XGETFLAGS =	-a
+
 all := 		TARGET = all
 clean :=	TARGET = clean
 clobber :=	TARGET = clobber
@@ -46,9 +49,15 @@ install_h:	$(ROOTHDRS)
 
 check:		$(CHECKHDRS)
 
+$(POFILE):	$(MSGFILES)
+		$(BUILDPO.msgfiles)
+
+_msg:		$(MSGDOMAINPOFILE)
+
 $(SUBDIRS): FRC
 	@cd $@; pwd; $(MAKE) $(TARGET)
 
 FRC:
 
+include $(SRC)/Makefile.msg.targ
 include ../Makefile.targ
diff --git a/usr/src/lib/libinetutil/Makefile.com b/usr/src/lib/libinetutil/Makefile.com
index cd3a0d6e33..231dadfb58 100644
--- a/usr/src/lib/libinetutil/Makefile.com
+++ b/usr/src/lib/libinetutil/Makefile.com
@@ -25,7 +25,8 @@
 
 LIBRARY = libinetutil.a
 VERS = 	  .1
-OBJECTS = octet.o inetutil.o ifspec.o ifaddrlist.o ifaddrlistx.o eh.o tq.o
+OBJECTS = octet.o inetutil.o ifspec.o ifaddrlist.o ifaddrlistx.o eh.o tq.o \
+	    ofmt.o
 
 include ../../Makefile.lib
 
@@ -38,7 +39,8 @@ SRCDIR =	../common
 COMDIR =	$(SRC)/common/net/dhcp
 SRCS = 		$(COMDIR)/octet.c $(SRCDIR)/inetutil.c \
 		$(SRCDIR)/ifspec.c $(SRCDIR)/eh.c $(SRCDIR)/tq.c \
-		$(SRCDIR)/ifaddrlist.c $(SRCDIR)/ifaddrlistx.c
+		$(SRCDIR)/ifaddrlist.c $(SRCDIR)/ifaddrlistx.c \
+		$(SRCDIR)/ofmt.c
 
 $(LINTLIB):=	SRCS = $(SRCDIR)/$(LINTSRC)
 LDLIBS +=	-lsocket -lc
diff --git a/usr/src/lib/libinetutil/common/llib-linetutil b/usr/src/lib/libinetutil/common/llib-linetutil
index 5e87f60dea..9dd868fa9f 100644
--- a/usr/src/lib/libinetutil/common/llib-linetutil
+++ b/usr/src/lib/libinetutil/common/llib-linetutil
@@ -2,9 +2,8 @@
  * CDDL HEADER START
  *
  * The contents of this file are subject to the terms of the
- * Common Development and Distribution License, Version 1.0 only
- * (the "License").  You may not use this file except in compliance
- * with the License.
+ * 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.
@@ -20,13 +19,12 @@
  * CDDL HEADER END
  */
 /*
- * Copyright (c) 2001 by Sun Microsystems, Inc.
- * All rights reserved.
+ * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
+ * Use is subject to license terms.
  */
 
-#pragma ident	"%Z%%M%	%I%	%E% SMI"
-
 /* LINTLIBRARY */
 /* PROTOLIB1 */
 
 #include <libinetutil.h>
+#include <ofmt.h>
diff --git a/usr/src/lib/libinetutil/common/mapfile-vers b/usr/src/lib/libinetutil/common/mapfile-vers
index cd0d88de08..8bc79dd4cb 100644
--- a/usr/src/lib/libinetutil/common/mapfile-vers
+++ b/usr/src/lib/libinetutil/common/mapfile-vers
@@ -63,6 +63,11 @@ SUNWprivate_1.1 {
 	iu_unregister_event;
 	octet_to_hexascii;
 	sockaddrcmp;
+	ofmt_open;
+	ofmt_close;
+	ofmt_print;
+	ofmt_update_winsize;
+	ofmt_strerror;
     local:
 	*;
 };
diff --git a/usr/src/lib/libinetutil/common/ofmt.c b/usr/src/lib/libinetutil/common/ofmt.c
new file mode 100644
index 0000000000..2f9fe3f91d
--- /dev/null
+++ b/usr/src/lib/libinetutil/common/ofmt.c
@@ -0,0 +1,480 @@
+/*
+ * 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.
+ */
+#include <errno.h>
+#include <sys/types.h>
+#include <stdlib.h>
+#include <string.h>
+#include <strings.h>
+#include <stdio.h>
+#include <ofmt.h>
+#include <sys/termios.h>
+#include <unistd.h>
+#include <sys/sysmacros.h>
+#include <libintl.h>
+
+/*
+ * functions and structures to internally process a comma-separated string
+ * of fields selected for output.
+ */
+typedef struct {
+	char	*s_buf;
+	const char **s_fields;	/* array of pointers to the fields in s_buf */
+	uint_t	s_nfields;	/* the number of fields in s_buf */
+} split_t;
+static void splitfree(split_t *);
+static split_t *split_str(const char *, uint_t);
+static split_t *split_fields(const ofmt_field_t *, uint_t, uint_t);
+
+/*
+ * The state of the output is tracked in a ofmt_state_t structure.
+ * Each os_fields[i] entry points at an ofmt_field_t array for
+ * the sub-command whose contents are provided by the caller, with
+ * os_nfields set to the number of requested fields.
+ */
+typedef struct ofmt_state_s {
+	ofmt_field_t  	*os_fields;
+	uint_t		os_nfields;
+	boolean_t	os_lastfield;
+	uint_t		os_overflow;
+	struct winsize	os_winsize;
+	int		os_nrow;
+	boolean_t	os_parsable;
+	int		os_nbad;
+	char		**os_badfields;
+} ofmt_state_t;
+/*
+ * A B_TRUE return value from the callback function will print out the contents
+ * of the output buffer, except when the buffer is returned with the empty
+ * string "", in which case the  OFMT_VAL_UNDEF will be printed.
+ *
+ * If the callback function returns B_FALSE, the "?" string will be emitted.
+ */
+#define	OFMT_VAL_UNDEF		"--"
+#define	OFMT_VAL_UNKNOWN	"?"
+static void ofmt_print_header(ofmt_state_t *);
+static void ofmt_print_field(ofmt_state_t *, ofmt_field_t *, const char *,
+    boolean_t);
+
+/*
+ * Split `str' into at most `maxfields' fields, Return a pointer to a
+ * split_t containing the split fields, or NULL on failure.
+ */
+static split_t *
+split_str(const char *str, uint_t maxfields)
+{
+	char	*field, *token, *lasts = NULL;
+	split_t	*sp;
+
+	if (*str == '\0' || maxfields == 0)
+		return (NULL);
+
+	sp = calloc(sizeof (split_t), 1);
+	if (sp == NULL)
+		return (NULL);
+
+	sp->s_buf = strdup(str);
+	sp->s_fields = malloc(sizeof (char *) * maxfields);
+	if (sp->s_buf == NULL || sp->s_fields == NULL)
+		goto fail;
+
+	token = sp->s_buf;
+	while ((field = strtok_r(token, ",", &lasts)) != NULL) {
+		if (sp->s_nfields == maxfields)
+			goto fail;
+		token = NULL;
+		sp->s_fields[sp->s_nfields++] = field;
+	}
+	return (sp);
+fail:
+	splitfree(sp);
+	return (NULL);
+}
+
+/*
+ * Split `fields' into at most `maxfields' fields. Return a pointer to
+ * a split_t containing the split fields, or NULL on failure. Invoked
+ * when all fields are implicitly selected at handle creation by
+ * passing in a NULL fields_str
+ */
+static split_t *
+split_fields(const ofmt_field_t *template, uint_t maxfields, uint_t maxcols)
+{
+	split_t	*sp;
+	int i, cols;
+
+	sp = calloc(sizeof (split_t), 1);
+	if (sp == NULL)
+		return (NULL);
+
+	sp->s_fields = malloc(sizeof (char *) * maxfields);
+	if (sp->s_fields == NULL)
+		goto fail;
+	cols = 0;
+	for (i = 0; i < maxfields; i++) {
+		cols += template[i].of_width;
+		/*
+		 * If all fields are implied without explicitly passing
+		 * in a fields_str, build a list of field names, stopping
+		 * when we run out of columns.
+		 */
+		if (maxcols > 0 && cols > maxcols)
+			break;
+		sp->s_fields[sp->s_nfields++] = template[i].of_name;
+	}
+	return (sp);
+fail:
+	splitfree(sp);
+	return (NULL);
+}
+
+/*
+ * Free the split_t structure pointed to by `sp'.
+ */
+static void
+splitfree(split_t *sp)
+{
+	if (sp == NULL)
+		return;
+	free(sp->s_buf);
+	free(sp->s_fields);
+	free(sp);
+}
+
+/*
+ * Open a handle to be used for printing formatted output.
+ */
+ofmt_status_t
+ofmt_open(const char *str, ofmt_field_t *template, uint_t flags,
+    uint_t maxcols, ofmt_handle_t *ofmt)
+{
+	split_t		*sp;
+	uint_t		i, j, of_index;
+	ofmt_field_t	*of;
+	ofmt_state_t	*os;
+	int		nfields = 0;
+	ofmt_status_t	err = OFMT_SUCCESS;
+	boolean_t	parsable = (flags & OFMT_PARSABLE);
+
+	*ofmt = NULL;
+	if (parsable) {
+		/*
+		 * For parsable output mode, the caller always needs
+		 * to specify precisely which fields are to be selected,
+		 * since the set of fields may change over time.
+		 */
+		if (str == NULL || str[0] == '\0')
+			return (OFMT_EPARSENONE);
+		if (strcmp(str, "all") == 0)
+			return (OFMT_EPARSEALL);
+	}
+	if (template == NULL)
+		return (OFMT_ENOTEMPLATE);
+	for (of = template; of->of_name != NULL; of++)
+		nfields++;
+	/*
+	 * split str into the columns selected, or construct the
+	 * full set of columns (equivalent to -o all).
+	 */
+	if (str != NULL && strcmp(str, "all") != 0) {
+		sp = split_str(str, nfields);
+	} else {
+		if (parsable || (str != NULL && strcmp(str, "all") == 0))
+			maxcols = 0;
+		sp = split_fields(template, nfields, maxcols);
+	}
+	if (sp == NULL)
+		goto nomem;
+
+	os = calloc(sizeof (ofmt_state_t) +
+	    sp->s_nfields * sizeof (ofmt_field_t), 1);
+	if (os == NULL)
+		goto nomem;
+	*ofmt = os;
+	os->os_fields = (ofmt_field_t *)&os[1];
+	os->os_parsable = parsable;
+	of = os->os_fields;
+	of_index = 0;
+	/*
+	 * sp->s_nfields is the number of fields requested in fields_str.
+	 * nfields is the number of fields in template.
+	 */
+	for (i = 0; i < sp->s_nfields; i++) {
+		for (j = 0; j < nfields; j++) {
+			if (strcasecmp(sp->s_fields[i],
+			    template[j].of_name) == 0) {
+				break;
+			}
+		}
+		if (j == nfields) {
+			int nbad = os->os_nbad++;
+
+			err = OFMT_EBADFIELDS;
+			if (os->os_badfields == NULL) {
+				os->os_badfields = malloc(sp->s_nfields *
+				    sizeof (char *));
+				if (os->os_badfields == NULL)
+					goto nomem;
+			}
+			os->os_badfields[nbad] = strdup(sp->s_fields[i]);
+			if (os->os_badfields[nbad] == NULL)
+				goto nomem;
+			continue;
+		}
+		of[of_index].of_name = strdup(template[j].of_name);
+		if (of[of_index].of_name == NULL)
+			goto nomem;
+		of[of_index].of_width = template[j].of_width;
+		of[of_index].of_id = template[j].of_id;
+		of[of_index].of_cb = template[j].of_cb;
+		of_index++;
+	}
+	splitfree(sp);
+	if (of_index == 0) /* all values in str are bogus */
+		return (OFMT_ENOFIELDS);
+	os->os_nfields = of_index; /* actual number of fields printed */
+	ofmt_update_winsize(*ofmt);
+	return (err);
+nomem:
+	err = OFMT_ENOMEM;
+	if (os != NULL)
+		ofmt_close(os);
+	*ofmt = NULL;
+	splitfree(sp);
+	return (err);
+}
+
+/*
+ * free resources associated with the ofmt_handle_t
+ */
+void
+ofmt_close(ofmt_handle_t ofmt)
+{
+	ofmt_state_t *os = ofmt;
+	int i;
+
+	if (os == NULL)
+		return;
+	for (i = 0; i < os->os_nfields; i++)
+		free(os->os_fields[i].of_name);
+	for (i = 0; i < os->os_nbad; i++)
+		free(os->os_badfields[i]);
+	free(os->os_badfields);
+	free(os);
+}
+
+/*
+ * Print the value for the selected field by calling the callback-function
+ * registered for the field.
+ */
+static void
+ofmt_print_field(ofmt_state_t *os, ofmt_field_t *ofp, const char *value,
+    boolean_t escsep)
+{
+	uint_t	width = ofp->of_width;
+	uint_t	valwidth;
+	uint_t	compress;
+	boolean_t parsable = os->os_parsable;
+	char	c;
+
+	/*
+	 * Parsable fields are separated by ':'. If such a field contains
+	 * a ':' or '\', this character is prefixed by a '\'.
+	 */
+	if (parsable) {
+		if (os->os_nfields == 1) {
+			(void) printf("%s", value);
+			return;
+		}
+		while ((c = *value++) != '\0') {
+			if (escsep && ((c == ':' || c == '\\')))
+				(void) putchar('\\');
+			(void) putchar(c);
+		}
+		if (!os->os_lastfield)
+			(void) putchar(':');
+		return;
+	} else {
+		if (value[0] == '\0')
+			value = OFMT_VAL_UNDEF;
+		if (os->os_lastfield) {
+			(void) printf("%s", value);
+			os->os_overflow = 0;
+			return;
+		}
+
+		valwidth = strlen(value);
+		if (valwidth + os->os_overflow >= width) {
+			os->os_overflow += valwidth - width + 1;
+			(void) printf("%s ", value);
+			return;
+		}
+
+		if (os->os_overflow > 0) {
+			compress = MIN(os->os_overflow, width - valwidth);
+			os->os_overflow -= compress;
+			width -= compress;
+		}
+		(void) printf("%-*s", width, value);
+	}
+}
+
+/*
+ * print one row of output values for the selected columns.
+ */
+void
+ofmt_print(ofmt_handle_t ofmt, void *arg)
+{
+	ofmt_state_t *os = ofmt;
+	int i;
+	char value[1024];
+	ofmt_field_t *of;
+	boolean_t escsep;
+	ofmt_arg_t ofarg;
+
+	if ((os->os_nrow++ % os->os_winsize.ws_row) == 0 && !os->os_parsable) {
+		ofmt_print_header(os);
+		os->os_nrow++;
+	}
+
+	of = os->os_fields;
+	escsep = (os->os_nfields > 1);
+	for (i = 0; i < os->os_nfields; i++) {
+		os->os_lastfield = (i + 1 == os->os_nfields);
+		value[0] = '\0';
+		ofarg.ofmt_id = of[i].of_id;
+		ofarg.ofmt_cbarg = arg;
+		if ((*of[i].of_cb)(&ofarg, value, sizeof (value)))
+			ofmt_print_field(os, &of[i], value, escsep);
+		else
+			ofmt_print_field(os, &of[i], OFMT_VAL_UNKNOWN, escsep);
+	}
+	(void) putchar('\n');
+	(void) fflush(stdout);
+}
+
+/*
+ * Print the field headers
+ */
+static void
+ofmt_print_header(ofmt_state_t *os)
+{
+	int i;
+	ofmt_field_t *of = os->os_fields;
+	boolean_t escsep = (os->os_nfields > 1);
+
+	for (i = 0; i < os->os_nfields; i++) {
+		os->os_lastfield = (i + 1 == os->os_nfields);
+		ofmt_print_field(os, &of[i], of[i].of_name, escsep);
+	}
+	(void) putchar('\n');
+}
+
+/*
+ * Update the current window size.
+ */
+void
+ofmt_update_winsize(ofmt_handle_t ofmt)
+{
+	ofmt_state_t *os = ofmt;
+	struct winsize *winsize = &os->os_winsize;
+
+	if (ioctl(1, TIOCGWINSZ, winsize) == -1 ||
+	    winsize->ws_col == 0 || winsize->ws_row == 0) {
+		winsize->ws_col = 80;
+		winsize->ws_row = 24;
+	}
+}
+
+/*
+ * Return error diagnostics using the information in the ofmt_handle_t
+ */
+char *
+ofmt_strerror(ofmt_handle_t ofmt, ofmt_status_t err, char *buf, uint_t bufsize)
+{
+	ofmt_state_t *os = ofmt;
+	int i;
+	const char *s;
+	char ebuf[OFMT_BUFSIZE];
+
+	/*
+	 * ebuf is intended for optional error-specific data to be appended
+	 * after the internationalized error string for an error code.
+	 */
+	ebuf[0] = '\0';
+
+	switch (err) {
+	case OFMT_SUCCESS:
+		s = "success";
+		break;
+	case OFMT_EBADFIELDS:
+		/*
+		 * Enumerate the singular/plural version of the warning
+		 * and error to simplify and improve localization.
+		 */
+		if (!os->os_parsable) {
+			if (os->os_nbad > 1)
+				s = "ignoring unknown output fields:";
+			else
+				s = "ignoring unknown output field:";
+		} else {
+			if (os->os_nbad > 1)
+				s = "unknown output fields:";
+			else
+				s = "unknown output field:";
+		}
+		/* set up the bad fields in ebuf */
+		for (i = 0; i < os->os_nbad; i++) {
+			(void) strlcat(ebuf, " `", sizeof (ebuf));
+			(void) strlcat(ebuf, os->os_badfields[i],
+			    sizeof (ebuf));
+			(void) strlcat(ebuf, "'", sizeof (ebuf));
+		}
+		break;
+	case OFMT_ENOFIELDS:
+		s = "no valid output fields";
+		break;
+	case OFMT_EPARSEALL:
+		s = "output field `all' invalid in parsable mode";
+		break;
+	case OFMT_EPARSENONE:
+		s = "output fields must be specified in parsable mode";
+		break;
+	case OFMT_ENOTEMPLATE:
+		s = "no template provided for fields";
+		break;
+	case OFMT_ENOMEM:
+		s = strerror(ENOMEM);
+		break;
+	default:
+		(void) snprintf(buf, bufsize,
+		    dgettext(TEXT_DOMAIN, "unknown ofmt error (%d)"),
+		    err);
+		return (buf);
+	}
+	(void) snprintf(buf, bufsize, dgettext(TEXT_DOMAIN, s));
+	(void) strlcat(buf, ebuf, bufsize);
+	return (buf);
+}
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 */