1.Dd Aug 19, 2012 2.Dt XPRINTF_DOMAIN 3 3.Os Darwin 4.Sh NAME 5.Nm copy_printf_domain , free_printf_domain , new_printf_domain , 6.Nm register_printf_domain_function , register_printf_domain_render_std 7.Nd extensible printf domains 8.Sh SYNOPSIS 9.In printf.h 10.Ft printf_domain_t 11.Fn copy_printf_domain "printf_domain_t domain" 12.Ft void 13.Fn free_printf_domain "printf_domain_t domain" 14.Ft printf_domain_t 15.Fn new_printf_domain void 16.Ft int 17.Fn register_printf_domain_function "printf_domain_t domain" "int spec" "printf_function *render" "printf_arginfo_function *arginfo", "void *context" 18.Ft int 19.Fn register_printf_domain_render_std "printf_domain_t domain" "const char *specs" 20.Sh DESCRIPTION 21A printf domain is an extensible printf (see 22.Xr xprintf 5 ) 23structure defining a set of conversion specifiers that 24will be used in calls to the routines discussed in 25.Xr xprintf 3 26and 27.Xr xprintf_comp 3 . 28Domains can be modified independently of one another, and do not affect the 29behavior of the normal printf calls in 30.Xr printf 3 . 31.Pp 32To create a new domain, call 33.Fn new_printf_domain ; 34the standard POSIX conversion specifiers are defined by default. 35To make a copy of an existing domain, use 36.Fn copy_printf_domain . 37When a domain is no longer needed, call 38.Fn free_printf_domain 39to release the associated memory. 40.Pp 41The 42.Fn register_printf_domain_function 43function is used to add, modify or remove conversion specifiers for a 44given domain. 45The 46.Fa spec 47argument is the specifier character, which can be any printable (non-control) 48ASCII character, 49except for those characters that are used as flag/option characters. 50The set of flag/option characters includes the space character, and the 51following: 52.Pp 53.Dl # $ ' * + \&, - \&. 0 1 2 3 4 5 6 7 8 9 \&: \&; L _ h j l q t v z 54.Pp 55Two user-defined callback function must also be given; see 56.Xr xprintf 5 57for a description of these callback functions and an example of use. 58Setting either or both callbacks to 59.Dv NULL 60deletes the given specifier from the domain. 61Note that while it is permissible to redefine the standard conversion 62specifiers, it is not usually recommended as it may cause confusion. 63.Pp 64The 65.Fn register_printf_domain_render_std 66function is used to add pre-defined conversion specifiers to the given domain. 67The 68.Fa specs 69argument is a null-terminated C string containing one or more of the following 70specifier characters: 71.Bl -tag -width ".Li H" 72.It Li H 73Hex dump. 74The 75.Sq Li H 76specifier takes two arguments; the first is a pointer to the data to 77dump, while the second argument is the length of the data, given as type 78.Vt unsigned . 79Normally, 16 characters are displayed per line, as pairs of hex characters 80separated by spaces. 81Specifying a field width less than 16 will display that number of characters 82per line. 83Setting the 84.Sq Li + 85(showsign) flag will prefix each line with the hex offset of the beginning 86character in that line. 87Setting the 88.Sq Li # 89(alternate form) flag will postfix an ASCII representation to each line, with 90.Sq Li \&. 91representing non-printable characters. 92.It Li M 93Errno. 94The 95.Sq Li M 96specifier displayed the text representation of the given 97.Vt int 98argument, expected to be a valid 99.Va errno 100value (as returned by 101.Xr strerror 3 ) . 102Invalid errno values are represent by the 103.Dq Li errno= 104string followed by the decimal and hex values of the argument. 105.It Li Q 106Quoted. 107The 108.Sq Li Q 109specifier displays a null-terminated string argument as a C string, with 110leading and trailing double quotes. 111Newlines, carriage-returns and tabs are represented by 112.Sq Li \en , 113.Sq Li \er 114and 115.Sq Li \et , 116respectively, while backslashes and double quotes are preceeded with a 117backslash. 118All other whitespace characters not including space itself (those in which 119.Xr isspace 3 120returns true) are displayed as octal escape sequences (a backslash followed by 121three octal digits). 122All other characters print as themselves. 123.It Li T 124time_t/timeval/timespec. 125The 126.Sq Li T 127specifier displays the three types of time values as a single decimal value. 128The argument should be a pointer to the time value to be converted. 129Setting the appropriate flags indicates which type is indicated: 130.Bl -tag -width ".Pq none" 131.It Li ll 132The 133.Sq Li ll 134(long long) flag indicates the argument points to a 135.Vt struct timespec 136structure. 137The default precision is 9. 138.It Li l 139The 140.Sq Li l 141(long) flag indicates the argument points to a 142.Vt struct timeval 143structure. 144The default precision is 6. 145.It Pq none 146By default, the argument points to a 147.Vt time_t 148value. 149The default precision is 0 (the fractional part is not displayed). 150.El 151.Pp 152If the 153.Sq Li # 154(alternate form) flag is specified, the value is displayed in years, days, 155hours, minutes and seconds, as in: 156.Dq Li 3y123d21h59m59s.987654 157(zero values are not displayed at all). 158Note that the years are 365 days (no leap days). 159.It Li V 160String vis. 161The 162.Sq Li V 163specifier uses 164.Xr strvisx 3 165to display the null-terminated C string argument. 166The precision value can be used to limit the amount of the string that is 167processed (defaults to the entire string). 168.Pp 169Flag values can be used to obtain different encodings: 170.Bl -tag -width "(none)" 171.It Li + 172The 173.Sq Li + 174(showsign) flag uses the 175.Dq Li VIS_WHITE | VIS_HTTPSTYLE 176flag value to 177.Xr strvisx 3 . 178.It Li 0 179The 180.Sq Li 0 181(leading zero) flag uses the 182.Dq Li VIS_WHITE | VIS_OCTAL 183flag value to 184.Xr strvisx 3 . 185.It Li # 186The 187.Sq Li # 188(alternate form) flag uses the 189.Dq Li VIS_WHITE 190flag value to 191.Xr strvisx 3 . 192.It Pq none 193The default flag value to 194.Xr strvisx 3 195is 196.Dq Li VIS_WHITE | VIS_CSTYLE | VIS_OCTAL . 197.El 198.El 199.Sh RETURN VALUES 200The 201.Fn new_printf_domain 202and 203.Fn copy_printf_domain 204functions return the new domain, or 205.Dv NULL 206on failure (usually out of memory condition). 207.Pp 208The 209.Fn register_printf_domain_function 210and 211.Fn register_printf_domain_render_std 212return zero on success and \-1 on failure (usually due to an improper specifier 213character or out of memory condition). 214.Sh SEE ALSO 215.Xr printf 3 , 216.Xr strvisx 3 , 217.Xr xprintf 3 , 218.Xr xprintf_comp 3 , 219.Xr xprintf 5 220