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" 36.Fc 37.Ft void 38.Fo ofmt_print 39.Fa "ofmt_handle_t ofmt" 40.Fa "void *cbarg" 41.Fc 42.Ft void 43.Fo ofmt_update_winsize 44.Fa "ofmt_handle_t ofmt" 45.Fc 46.Ft "char *" 47.Fo ofmt_strerror 48.Fa "ofmt_handle_t ofmt" 49.Fa "ofmt_status_t error" 50.Fa "char *buf" 51.Fa "uint_t bufsize" 52.Fc 53.Ft void 54.Fo ofmt_close 55.Fa "ofmt_handle_t ofmt" 56.Fc 57.Sh DESCRIPTION 58The 59.Nm libofmt 60library provides data structures and routines for printing output. 61.Pp 62Currently this is an internal interface. 63The interface can and will change without notice as the project needs, at any 64time. 65.Pp 66All output is assumed to be in a columnar format, where each column represents 67a field to be printed out. 68Multiple fields in parsable output are separated by 69.Sq \&: , 70with the 71.Sq \&: 72character itself escaped by a 73.Sq \e 74.Po e.g., IPv6 addresses may be printed as 75.Qq fe80\e:\e:1 76.Pc ; 77single field output is printed as-is. 78In multiline mode, every 79.Bq field,value 80pair is printed in a line of its own, thus: 81.Qq field: value . 82.Ss Data Structures 83The 84.Vt ofmt_field_t 85data structure used in 86.Sx ofmt_open 87is defined as follows: 88.Bd -literal 89typedef struct ofmt_field_s { 90 char *of_name; /* column name */ 91 uint_t of_width; /* output column width */ 92 uint_t of_id; /* implementation specific cookie */ 93 ofmt_cb_t *of_cb; /* callback function defined by caller */ 94} ofmt_field_t; 95.Ed 96.Pp 97The 98.Vt ofmt_arg_t 99data structure which is passed to callback function is defined as follows: 100.Bd -literal 101typedef struct ofmt_arg_s { 102 uint_t ofmt_id; /* implementation specific cookie */ 103 uint_t ofmt_width; /* output column width */ 104 uint_t ofmt_index; /* unused */ 105 void *ofmt_cbarg; /* argument passed to ofmt_print() */ 106} ofmt_arg_t; 107.Ed 108.Ss Fn ofmt_open 109The 110.Fn ofmt_open 111function opens a handle returned in 112.Fa ofmt 113for each set of fields to be printed. 114.Pp 115.Fa fields 116is a comma-separated list of the fields that have been selected for output 117.Po typically the string passed to 118.Fl o 119in the command-line 120.Pc . 121Columns selected for output are identified by a match between the 122.Va of_name 123value in the 124.Fa template 125and the 126.Fa fields 127requested. 128In human-friendly 129.Pq non machine-parsable 130mode, 131.Dv NULL 132.Fa fields , 133or a value of 134.Qq all 135is treated as a request to print all allowable fields that fit other applicable 136constraints. 137.Pp 138.Fa template 139specifies the list of supported fields, along with formatting information 140.Pq e.g., field width , 141and a pointer to a callback function that can provide a string representation of 142the value to be printed out. 143The set of supported fields must be a 144.Dv NULL 145terminated array of type 146.Vt ofmt_field_t , 147described in 148.Sx Data Structures , 149as 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 158is the application-specified callback function with the following prototype that 159provides 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 164The interpretation of the 165.Va of_id 166field is completely private to the caller, and can be optionally used by the 167callback function as a cookie to identify the field being printed when a single 168callback function is shared between multiple 169.Fa template 170entries. 171.Pp 172The 173.Fa flags 174can be any valid combination of the following: 175.Pp 176.Bl -tag -width "OFMT_MULTILINE" -compact 177.It Dv OFMT_PARSABLE 178Machine-parsable mode. 179Specifying a null or empty 180.Va fields 181in the machine-parsable mode will result in a returned error value of 182.Dv OFMT_EPARSENONE . 183An attempt to create a handle in machine-parsable mode with the 184.Fa fields 185set to 186.Qq all 187will result in a returned error value of 188.Dv OFMT_EPARSEALL . 189.It Dv OFMT_WRAP 190Wrap output if field width is exceeded. 191Currently output is wrapped at whitespace or comma characters. 192.It Dv OFMT_MULTILINE 193Multiline mode. 194Specifying both 195.Dv OFMT_MULTILINE 196and 197.Dv OFMT_PARSABLE 198will result in 199.Dv OFMT_EPARSEMULTI . 200.It Dv OFMT_RIGHTJUST 201Right justified output. 202.El 203.Pp 204The non-zero 205.Fa maxcols 206limits the number of output columns. 207.Ss Fn ofmt_print 208The 209.Fn ofmt_print 210function prints a row of output. 211.Pp 212.Fa cbarg 213points at the arguments to be passed to the callback function for each column in 214the row. 215The call to 216.Fn ofmt_print 217will result in the callback function of each selected field invoked with 218.Va of_id , 219.Va of_width 220and 221.Fa cbarg 222embedded in 223.Fa ofmt_arg , 224described in 225.Sx Data Structures . 226.Pp 227The callback function should fill 228.Fa buf 229with the string to be printed for the field using the data in 230.Fa cbarg . 231.Ss Fn ofmt_update_winsize 232The 233.Fn ofmt_update_winsize 234function updates the window size information 235.Pq which is initially computed when the handle is created 236in the 237.Fa ofmt . 238If the 239.Dv TIOCGWINSZ 240ioctl fails, the window size is set to 80x24. 241.Ss Fn ofmt_strerror 242The 243.Fn ofmt_strerror 244function returns error diagnostics in 245.Fa buf 246using the information in the 247.Fa ofmt 248and 249.Fa error . 250.Pp 251Using a 252.Fa buf 253size of 254.Dv OFMT_BUFSIZE 255is recommended. 256.Ss Fn ofmt_close 257The 258.Fn ofmt_close 259function frees any resources allocated for the handle after printing is 260completed. 261.Sh RETURN VALUES 262If successful, the 263.Fn ofmt_open 264function will return 265.Dv OFMT_SUCCESS , 266with a non-null 267.Fa ofmt_handle . 268The function returns one of the failure codes 269.Po enumerated in 270.Vt ofmt_status_t 271.Pc 272listed below otherwise: 273.Pp 274.Bl -tag -width "OFMT_ENOTEMPLATE" -compact 275.It Dv OFMT_ENOMEM 276out of memory 277.It Dv OFMT_EBADFIELDS 278one or more bad fields with good fields 279.It Dv OFMT_ENOFIELDS 280no valid output fields 281.It Dv OFMT_EPARSEALL 282"all" is invalid in parsable mode 283.It Dv OFMT_EPARSENONE 284output fields missing in parsable mode 285.It Dv OFMT_EPARSEWRAP 286parsable mode incompatible with wrap mode 287.It Dv OFMT_ENOTEMPLATE 288no template provided for fields 289.It Dv OFMT_EPARSEMULTI 290parsable and multiline don't mix 291.El 292.Pp 293More information about the type of failure can be obtained by calling 294.Fn ofmt_strerror . 295.Pp 296The 297.Fn ofmt_strerror 298function returns the 299.Fa buf . 300.Sh INTERFACE STABILITY 301.Sy Private . 302.Sh SEE ALSO 303.Xr ioctl 2 , 304.Xr strerror 3C , 305.Xr attributes 5 306