1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2010 Sun Microsystems, Inc.  All rights reserved.
  13 .\" Copyright 2017 Nexenta Systems, Inc.

  14 .\"
  15 .Dd June 1, 2017
  16 .Dt OFMT 3OFMT
  17 .Os
  18 .Sh NAME
  19 .Nm ofmt_open ,
  20 .Nm ofmt_print ,
  21 .Nm ofmt_update_winsize ,
  22 .Nm ofmt_strerror ,
  23 .Nm ofmt_close
  24 .Nd data structures and routines for printing output
  25 .Sh LIBRARY
  26 .Lb libofmt
  27 .Sh SYNOPSIS
  28 .In ofmt.h
  29 .Ft ofmt_status_t
  30 .Fo ofmt_open
  31 .Fa "const char *fields"
  32 .Fa "const ofmt_field_t *template"
  33 .Fa "uint_t flags"
  34 .Fa "uint_t maxcols"
  35 .Fa "ofmt_handle_t *ofmt"

 141 and a pointer to a callback function that can provide a string representation of
 142 the value to be printed out.
 143 The set of supported fields must be a
 144 .Dv NULL
 145 terminated array of type
 146 .Vt ofmt_field_t ,
 147 described in
 148 .Sx Data Structures ,
 149 as follows:
 150 .Bd -literal -offset indent
 151 {<of_name>, <of_width>, <of_id>, <of_cb> },
 152 \&.\&.\&.
 153 {<of_name>, <of_width>, <of_id>, <of_cb> },
 154 {NULL, 0, 0, NULL}
 155 .Ed
 156 .Pp
 157 .Va of_cb
 158 is the application-specified callback function with the following prototype that
 159 provides a string representation of the value to be printed for the field:
 160 .Bd -literal -offset indent
 161 (*of_cb)(ofmt_arg_t *ofmt_arg, char *buf, uint_t bufsize)
 162 .Ed
 163 .Pp












 164 The interpretation of the
 165 .Va of_id
 166 field is completely private to the caller, and can be optionally used by the
 167 callback function as a cookie to identify the field being printed when a single
 168 callback function is shared between multiple
 169 .Fa template
 170 entries.
 171 .Pp
 172 The
 173 .Fa flags
 174 can be any valid combination of the following:
 175 .Pp
 176 .Bl -tag -width "OFMT_MULTILINE" -compact
 177 .It Dv OFMT_PARSABLE
 178 Machine-parsable mode.
 179 Specifying a null or empty
 180 .Va fields
 181 in the machine-parsable mode will result in a returned error value of
 182 .Dv OFMT_EPARSENONE .
 183 An attempt to create a handle in machine-parsable mode with the

   1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2010 Sun Microsystems, Inc.  All rights reserved.
  13 .\" Copyright 2017 Nexenta Systems, Inc.
  14 .\" Copyright 2018 Joyent, Inc.
  15 .\"
  16 .Dd December 20, 2018
  17 .Dt OFMT 3OFMT
  18 .Os
  19 .Sh NAME
  20 .Nm ofmt_open ,
  21 .Nm ofmt_print ,
  22 .Nm ofmt_update_winsize ,
  23 .Nm ofmt_strerror ,
  24 .Nm ofmt_close
  25 .Nd data structures and routines for printing output
  26 .Sh LIBRARY
  27 .Lb libofmt
  28 .Sh SYNOPSIS
  29 .In ofmt.h
  30 .Ft ofmt_status_t
  31 .Fo ofmt_open
  32 .Fa "const char *fields"
  33 .Fa "const ofmt_field_t *template"
  34 .Fa "uint_t flags"
  35 .Fa "uint_t maxcols"
  36 .Fa "ofmt_handle_t *ofmt"

 142 and a pointer to a callback function that can provide a string representation of
 143 the value to be printed out.
 144 The set of supported fields must be a
 145 .Dv NULL
 146 terminated array of type
 147 .Vt ofmt_field_t ,
 148 described in
 149 .Sx Data Structures ,
 150 as follows:
 151 .Bd -literal -offset indent
 152 {<of_name>, <of_width>, <of_id>, <of_cb> },
 153 \&.\&.\&.
 154 {<of_name>, <of_width>, <of_id>, <of_cb> },
 155 {NULL, 0, 0, NULL}
 156 .Ed
 157 .Pp
 158 .Va of_cb
 159 is the application-specified callback function with the following prototype that
 160 provides a string representation of the value to be printed for the field:
 161 .Bd -literal -offset indent
 162 boolean_t (*of_cb)(ofmt_arg_t *ofmt_arg, char *buf, uint_t bufsize)
 163 .Ed
 164 .Pp
 165 The callback must not write beyond
 166 .Fa bufsize
 167 bytes of the string form into
 168 .Fa buf .
 169 If the function successfully translates the field into its string
 170 representation and places it into
 171 .Fa buf ,
 172 then the callback function should return
 173 .Dv B_TRUE .
 174 Otherwise, the callback function should return
 175 .Dv B_FALSE .
 176 .Pp
 177 The interpretation of the
 178 .Va of_id
 179 field is completely private to the caller, and can be optionally used by the
 180 callback function as a cookie to identify the field being printed when a single
 181 callback function is shared between multiple
 182 .Fa template
 183 entries.
 184 .Pp
 185 The
 186 .Fa flags
 187 can be any valid combination of the following:
 188 .Pp
 189 .Bl -tag -width "OFMT_MULTILINE" -compact
 190 .It Dv OFMT_PARSABLE
 191 Machine-parsable mode.
 192 Specifying a null or empty
 193 .Va fields
 194 in the machine-parsable mode will result in a returned error value of
 195 .Dv OFMT_EPARSENONE .
 196 An attempt to create a handle in machine-parsable mode with the