Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

XPRINTF_DOMAIN(3)        BSD Library Functions Manual        XPRINTF_DOMAIN(3)

NAME
     copy_printf_domain, free_printf_domain, new_printf_domain, register_printf_domain_function,
     register_printf_domain_render_std -- extensible printf domains

SYNOPSIS
     #include <printf.h>

     printf_domain_t
     copy_printf_domain(printf_domain_t domain);

     void
     free_printf_domain(printf_domain_t domain);

     printf_domain_t
     new_printf_domain(void);

     int
     register_printf_domain_function(printf_domain_t domain, int spec, printf_function *render,
         printf_arginfo_function *arginfo);, void *context

     int
     register_printf_domain_render_std(printf_domain_t domain, const char *specs);

DESCRIPTION
     A printf domain is an extensible printf (see xprintf(5)) structure defining a set of conversion speci-fiers specifiers
     fiers that will be used in calls to the routines discussed in xprintf(3) and xprintf_comp(3).  Domains
     can be modified independently of one another, and do not affect the behavior of the normal printf calls
     in printf(3).

     To create a new domain, call new_printf_domain(); the standard POSIX conversion specifiers are defined
     by default.  To make a copy of an existing domain, use copy_printf_domain().  When a domain is no
     longer needed, call free_printf_domain() to release the associated memory.

     The register_printf_domain_function() function is used to add, modify or remove conversion specifiers
     for a given domain.  The spec argument is the specifier character, which can be any printable (non-con-trol) (non-control)
     trol) 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:

           # $ ' * + , - . 0 1 2 3 4 5 6 7 8 9 : ; L _ h j l q t v z

     Two user-defined callback function must also be given; see xprintf(5) for a description of these call-back callback
     back functions and an example of use.  Setting either or both callbacks to NULL deletes the given spec-ifier specifier
     ifier from the domain.  Note that while it is permissible to redefine the standard conversion speci-fiers, specifiers,
     fiers, it is not usually recommended as it may cause confusion.

     The register_printf_domain_render_std() function is used to add pre-defined conversion specifiers to
     the given domain.  The specs argument is a null-terminated C string containing one or more of the fol-lowing following
     lowing specifier characters:

     H  Hex dump.  The `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 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 `+' (showsign) flag will pre-fix prefix
        fix each line with the hex offset of the beginning character in that line.  Setting the `#' (alter-nate (alternate
        nate form) flag will postfix an ASCII representation to each line, with `.' representing non-print-able non-printable
        able characters.

     M  Errno.  The `M' specifier displayed the text representation of the given int argument, expected to
        be a valid errno value (as returned by strerror(3)).  Invalid errno values are represent by the
        ``errno='' string followed by the decimal and hex values of the argument.

     Q  Quoted.  The `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 `\n', `\r' and
        `\t', respectively, while backslashes and double quotes are preceeded with a backslash.  All other
        whitespace characters not including space itself (those in which isspace(3) returns true) are dis-played displayed
        played as octal escape sequences (a backslash followed by three octal digits).  All other characters
        print as themselves.

     T  time_t/timeval/timespec.  The `T' specifier displays the three types of time values as a single dec-imal decimal
        imal value.  The argument should be a pointer to the time value to be converted.  Setting the appro-priate appropriate
        priate flags indicates which type is indicated:

        ll      The `ll' (long long) flag indicates the argument points to a struct timespec structure.  The
                default precision is 9.

        l       The `l' (long) flag indicates the argument points to a struct timeval structure.  The
                default precision is 6.

        (none)  By default, the argument points to a time_t value.  The default precision is 0 (the frac-tional fractional
                tional part is not displayed).

        If the `#' (alternate form) flag is specified, the value is displayed in years, days, hours, minutes
        and seconds, as in: ``3y123d21h59m59s.987654'' (zero values are not displayed at all).  Note that
        the years are 365 days (no leap days).

     V  String vis.  The `V' specifier uses 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).

        Flag values can be used to obtain different encodings:

        +       The `+' (showsign) flag uses the ``VIS_WHITE | VIS_HTTPSTYLE'' flag value to strvisx(3).

        0       The `0' (leading zero) flag uses the ``VIS_WHITE | VIS_OCTAL'' flag value to strvisx(3).

        #       The `#' (alternate form) flag uses the ``VIS_WHITE'' flag value to strvisx(3).

        (none)  The default flag value to strvisx(3) is ``VIS_WHITE | VIS_CSTYLE | VIS_OCTAL''.

RETURN VALUES
     The new_printf_domain() and copy_printf_domain() functions return the new domain, or NULL on failure
     (usually out of memory condition).

     The register_printf_domain_function() and 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).

SEE ALSO
     printf(3), strvisx(3), xprintf(3), xprintf_comp(3), xprintf(5)

Darwin                           Aug 19, 2012                           Darwin