vsprintf(3)                                                 vsprintf(3)

  printf()

  NAME

    printf(), fprintf(), sprintf(), snprintf(), vprintf(), vfprintf(),
    vsprintf(), vsnprintf() - formatted output conversion

  SYNOPSIS

    #include 

    int printf (const char *format ...)
    int fprintf (FILE *stream, const char *format ...)
    int sprintf (char *str, const char *format ...)
    int snprintf (char *str, size_t size, const char *format ...)

    #include 

    int vprintf (const char *format, va_list ap)
    int vfprintf (FILE *stream, const char *format, va_list ap)
    int vsprintf (char *str, const char *format, va_list ap)
    int vsnprintf (char *str, size_t size, const char *format, va_list ap)

  DESCRIPTION

    The functions in the printf(3) family produce output according to a
    format, as described below. Printf(3) and vprintf(3) write output to
    stdout, the standard output stream; fprintf(3) and vfprintf(3) write
    output to the specified output stream; sprintf(3), snprintf(3),
    vsprintf(3), and vsnprintf(3) write to the character string str.

    These functions return the number of characters printed (not including the
    trailing \0 used to end output to strings). Sprintf(3) and vsprintf(3)
    effectively assume an infinite size.

    Snprintf(3) and vsnprintf(3) write at most size-1 of the characters
    printed into the output string (the size'th character then get the
    terminating \0); if the return value is greater than or equal to the size,
    the string was too short and some of the printed characters were
    discarded. Sprintf(3) and vsprintf(3) effectively assume an infinite size.

    The output is written according to the format string that specifies how
    subsequent arguments (or arguments accessed through the variable-length
    argument facilities of ) are converted for output.

    The format string contains zero or more directives; a directive is either
    an ordinary character (any character but %), which is copied unchanged to
    the output stream. The format string is composed of zero or more
    directives: ordinary characters (not %), which are copied unchanged to the
    output stream; or a conversion specification. A conversion specification
    fetches zero or more subsequent arguments. Each conversion specification
    is introduced by the character %. The arguments must correspond properly
    (after type promotion) with the conversion specifier. The syntax of a
    conversion specifier is:

    %[#][0][-][ ][+][width][.[precision]][h|l|L|q]type

    Only the type is required.

    In sequence, these flags are:

    #
        A # character specifies that the value should be converted to an
        "alternate form". This affects only o, x, X, e, E, f, g, and G
        conversions.
        *     For o conversions, the precision of the number is increased to
              force the first character of the output string to a zero (except
              if a zero value is printed with an explicit precision of zero).
        *     For x and X conversions, a non-zero result has the string 0x (or
              0X for X conversions) prepended to it.
        *     For e, E, f, conversions, the result will always contain a
              decimal point, even if no digits follow it (normally, a decimal
              point appears in the results of those conversions only if a
              digit follows).
        *     For g and G conversions, the result will always contain a
              decimal point, even if no digits follow it, and trailing zeros
              are not removed from the result as they would otherwise be.

    0
        A zero character specifies that padding on the left is done with zeros
        rather than blanks. For all conversions except n, the converted value
        is padded on the left with zeros rather than blanks. If a precision is
        given with a numeric conversion (d i, o, u, i, x, and X), the 0 flag
        is ignored.

    -
        A negative field width flag - indicates the converted value is to be
        left adjusted on the field boundary. Except for n conversions, the
        converted value is padded on the right with blanks, rather than on the
        left with blanks or zeros. A - overrides a 0 if both are given.
        A space specifies that a blank should be left before a positive number
        produced by a signed conversion (d e, E, f, g, G, or i).

    +
        A + character specifies that a sign always be placed before a number
        produced by a signed conversion. A + overrides a space if both are
        used.

    width
        This optional decimal digit string specifies a minimum field width. If
        the converted value has fewer characters than the field width, it will
        be padded with spaces on the left (or right, if the left-adjustment
        flag has been given) to fill out the field width.
        A field width may be indicated by an asterisk * instead of a digit
        string. In this case, an int argument supplies the field width. A
        negative field width is treated as a left adjustment flag followed by
        a positive field width.

    precision
        An optional precision, in the form of a period . followed by an
        optional digit string. If the digit string is omitted, the precision
        is taken as zero. This gives the minimum number of digits to appear
        for d, i, o, u, x, and X conversions, the number of digits to appear
        after the decimal-point for e, E, and f conversions, the maximum
        number of significant digits for g and G conversions, or the maximum
        number of characters to be printed from a string for s conversions.
        A precision may be indicated by an asterisk * instead of a digit
        string. In this case, an int argument supplies the precision. A
        negative precision is treated as though it were missing.
    h|l|L|q
        One of the optional characters h, l (ell), L, or q, depending on the
        conversion type The values are:

        h
            a following d, i, o, u, x, or X conversion corresponds to a short
            int or unsigned short int argument, or that a following n
            conversion corresponds to a pointer to a short int argument.

        l
            (ell) A following d, i, o, u, x, or X conversion applies to a
            pointer to a long int or unsigned long int argument, or that a
            following n conversion corresponds to a pointer to a long int
            argument.

        L
            A following e, E, f, g, or G conversion corresponds to a long
            double argument.

        q
            A following d, i, o, u, x, or X conversion applies to a pointer to
            a quad_t or u_quad_t (unsigned long int) argument, or that a
            following n conversion corresponds to a pointer to a quad_t
            argument. The types quad_t (extended precisions) and u_quad_t
            (unsigned extended precision) are defined in . Two l
            (ell) conversion option characters are equivalent to a single q.

    type
        A character that specifies the type of conversion to be applied.
        Type     Argument      Conversion

        %                      Prints literal % character

        c        int           Prints a character

        C        wchar_t       Prints a wide-character code; equivalent to
                               lc

        d        int           Signed decimal

        D        long int      Signed decimal; equivalent to ld

        e        double        Decimal in form [-]d.ddde[mdd]

        E        double        Decimal in form [-]d.dddE[mdd]

        f        double        Decimal in form [-]ddd.ddd

        g        double        The more compact of f or e format

        i        int           Signed decimal

        n        int *         Number of character printed so far stored in
                               argument

        o        int           Unsigned octal

        O        long int      Unsigned octal; equivalent to lo

        p        void *        Hexadecimal value of pointer, as for %#x or
                               %#lx

        s        char *        String

        S        wchar_t *     Wide-character string; equivalent to ls

        u        int           Unsigned decimal

        U        long int      Unsigned decimal; equivalent to lu

        X        int           Unsigned hexadecimal using letters ABCDEF

        x        int           Unsigned hexadecimal using letters abcdef

    Note:

    f
        The number of digits after the decimal-point character is equal to the
        precision specification. If the precision is missing, it is taken as
        6; if the precision is explicitly zero, no decimal-point character
        appears. If a decimal point appears, at least one digit appears before
        it.

    g
        The precision specifies the number of significant digits. If the
        precision is missing, 6 digits are given; if the precision is zero, it
        is treated as 1. Style e is used if the exponent from its conversion
        is less than -4 or greater than or equal to the precision. Trailing
        zeros are removed from the fractional part of the result; a decimal
        point appears only if it is followed by at least one digit.

    s
        The char * argument is expected to be a pointer to an array of
        character type (pointer to a string). Characters from the array are
        written up to (but not including) a terminating NUL character; if a
        precision is specified, no more than the number specified are written.
        If a precision is given, no null character need be present; if the
        precision is not specified, or is greater than the size of the array,
        the array must contain a terminating NUL character.

    n
        The number of characters written so far is stored into the integer
        indicated by the int * (or variant) pointer argument. No argument is
        converted.

    %
        A % is written. No argument is converted. The complete conversion
        specification is %%.

    In no case does a nonexistent or small field width cause truncation of a
    field; if the result of a conversion is wider than the field width, the
    field is expanded to contain the conversion result.

  EXAMPLES

    To print a date and time in the form `Sunday, July 3, 10:02', where
    weekday and month are pointers to strings:

    #include 
    fprintf(stdout, "%s, %s %d, %.2d:%.2d\n",
         weekday, month, day, hour, min);

    To print to five decimal places:

    #include 
    #include 
    fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));

    To allocate a 128-byte string and print into it:

    #include 
    #include 
    #include 
    char *nefmt(const char *fmt, ...)
    {
         char *p;
         va_list ap;
         if ((p = malloc(128)) == NULL)
              return (NULL);
         va_start(ap, fmt);
         (void) vsnprintf(p, 128, fmt, ap);
         va_end(ap);
         return (p);
    }

  SEE ALSO

    printf(1)

    scanf(3)

  USAGE NOTES

    All of these functions are thread safe.

    None of these functions are async-signal safe.