--- /dev/null
+.Dd Aug 19, 2012
+.Dt XPRINTF_DOMAIN 3
+.Os Darwin
+.Sh NAME
+.Nm copy_printf_domain , free_printf_domain , new_printf_domain ,
+.Nm register_printf_domain_function , register_printf_domain_render_std
+.Nd extensible printf domains
+.Sh SYNOPSIS
+.In printf.h
+.Ft printf_domain_t
+.Fn copy_printf_domain "printf_domain_t domain"
+.Ft void
+.Fn free_printf_domain "printf_domain_t domain"
+.Ft printf_domain_t
+.Fn new_printf_domain void
+.Ft int
+.Fn register_printf_domain_function "printf_domain_t domain" "int spec" "printf_function *render" "printf_arginfo_function *arginfo", "void *context"
+.Ft int
+.Fn register_printf_domain_render_std "printf_domain_t domain" "const char *specs"
+.Sh DESCRIPTION
+A printf domain is an extensible printf (see
+.Xr xprintf 5 )
+structure defining a set of conversion specifiers that
+will be used in calls to the routines discussed in
+.Xr xprintf 3
+and
+.Xr xprintf_comp 3 .
+Domains can be modified independently of one another, and do not affect the
+behavior of the normal printf calls in
+.Xr printf 3 .
+.Pp
+To create a new domain, call
+.Fn new_printf_domain ;
+the standard POSIX conversion specifiers are defined by default.
+To make a copy of an existing domain, use
+.Fn copy_printf_domain .
+When a domain is no longer needed, call
+.Fn free_printf_domain
+to release the associated memory.
+.Pp
+The
+.Fn register_printf_domain_function
+function is used to add, modify or remove conversion specifiers for a
+given domain.
+The
+.Fa spec
+argument is the specifier character, which can be any printable (non-control)
+ASCII character,
+except for those characters that are used as flag/option characters.
+The set of flag/option characters includes the space character, and the
+following:
+.Pp
+.Dl # $ ' * + \&, - \&. 0 1 2 3 4 5 6 7 8 9 \&: \&; L _ h j l q t v z
+.Pp
+Two user-defined callback function must also be given; see
+.Xr xprintf 5
+for a description of these callback functions and an example of use.
+Setting either or both callbacks to
+.Dv NULL
+deletes the given specifier from the domain.
+Note that while it is permissible to redefine the standard conversion
+specifiers, it is not usually recommended as it may cause confusion.
+.Pp
+The
+.Fn register_printf_domain_render_std
+function is used to add pre-defined conversion specifiers to the given domain.
+The
+.Fa specs
+argument is a null-terminated C string containing one or more of the following
+specifier characters:
+.Bl -tag -width ".Li H"
+.It Li H
+Hex dump.
+The
+.Sq Li H
+specifier takes two arguments; the first is a pointer to the data to
+dump, while the second argument is the length of the data, given as type
+.Vt unsigned .
+Normally, 16 characters are displayed per line, as pairs of hex characters
+separated by spaces.
+Specifying a field width less than 16 will display that number of characters
+per line.
+Setting the
+.Sq Li +
+(showsign) flag will prefix each line with the hex offset of the beginning
+character in that line.
+Setting the
+.Sq Li #
+(alternate form) flag will postfix an ASCII representation to each line, with
+.Sq Li \&.
+representing non-printable characters.
+.It Li M
+Errno.
+The
+.Sq Li M
+specifier displayed the text representation of the given
+.Vt int
+argument, expected to be a valid
+.Va errno
+value (as returned by
+.Xr strerror 3 ) .
+Invalid errno values are represent by the
+.Dq Li errno=
+string followed by the decimal and hex values of the argument.
+.It Li Q
+Quoted.
+The
+.Sq Li Q
+specifier displays a null-terminated string argument as a C string, with
+leading and trailing double quotes.
+Newlines, carriage-returns and tabs are represented by
+.Sq Li \en ,
+.Sq Li \er
+and
+.Sq Li \et ,
+respectively, while backslashes and double quotes are preceeded with a
+backslash.
+All other whitespace characters not including space itself (those in which
+.Xr isspace 3
+returns true) are displayed as octal escape sequences (a backslash followed by
+three octal digits).
+All other characters print as themselves.
+.It Li T
+time_t/timeval/timespec.
+The
+.Sq Li T
+specifier displays the three types of time values as a single decimal value.
+The argument should be a pointer to the time value to be converted.
+Setting the appropriate flags indicates which type is indicated:
+.Bl -tag -width ".Pq none"
+.It Li ll
+The
+.Sq Li ll
+(long long) flag indicates the argument points to a
+.Vt struct timespec
+structure.
+The default precision is 9.
+.It Li l
+The
+.Sq Li l
+(long) flag indicates the argument points to a
+.Vt struct timeval
+structure.
+The default precision is 6.
+.It Pq none
+By default, the argument points to a
+.Vt time_t
+value.
+The default precision is 0 (the fractional part is not displayed).
+.El
+.Pp
+If the
+.Sq Li #
+(alternate form) flag is specified, the value is displayed in years, days,
+hours, minutes and seconds, as in:
+.Dq Li 3y123d21h59m59s.987654
+(zero values are not displayed at all).
+Note that the years are 365 days (no leap days).
+.It Li V
+String vis.
+The
+.Sq Li V
+specifier uses
+.Xr strvisx 3
+to display the null-terminated C string argument.
+The precision value can be used to limit the amount of the string that is
+processed (defaults to the entire string).
+.Pp
+Flag values can be used to obtain different encodings:
+.Bl -tag -width "(none)"
+.It Li +
+The
+.Sq Li +
+(showsign) flag uses the
+.Dq Li VIS_WHITE | VIS_HTTPSTYLE
+flag value to
+.Xr strvisx 3 .
+.It Li 0
+The
+.Sq Li 0
+(leading zero) flag uses the
+.Dq Li VIS_WHITE | VIS_OCTAL
+flag value to
+.Xr strvisx 3 .
+.It Li #
+The
+.Sq Li #
+(alternate form) flag uses the
+.Dq Li VIS_WHITE
+flag value to
+.Xr strvisx 3 .
+.It Pq none
+The default flag value to
+.Xr strvisx 3
+is
+.Dq Li VIS_WHITE | VIS_CSTYLE | VIS_OCTAL .
+.El
+.El
+.Sh RETURN VALUES
+The
+.Fn new_printf_domain
+and
+.Fn copy_printf_domain
+functions return the new domain, or
+.Dv NULL
+on failure (usually out of memory condition).
+.Pp
+The
+.Fn register_printf_domain_function
+and
+.Fn register_printf_domain_render_std
+return zero on success and \-1 on failure (usually due to an improper specifier
+character or out of memory condition).
+.Sh SEE ALSO
+.Xr printf 3 ,
+.Xr strvisx 3 ,
+.Xr xprintf 3 ,
+.Xr xprintf_comp 3 ,
+.Xr xprintf 5
projects / apple / libc.git / blobdiff