stdio/xprintf_domain.3

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