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