### printf -- Print Formatted Characters

Format

>     #include <stdio.h>
>     int printf(const char *format-string, argument-list);

Language Level: ANSI, POSIX, XPG4, Extension
printf formats and prints a series of characters and values to the standard output stream stdout. The format-string consists of ordinary characters, escape sequences, and format specifications. The ordinary characters are copied in order of their appearance to stdout. Format specifications, beginning with a percent sign (%), determine the output format for any argument-list following the format-string. The format-string is a multibyte character string.

The format-string is read left to right. When the first format specification is found, the value of the first argument after the format-string is converted and output according to the format specification. The second format specification causes the second argument after the format-string to be converted and output, and so on through the end of the format-string. If there are more arguments than there are format specifications, the extra arguments are evaluated and ignored. The results are undefined if there are not enough arguments for all the format specifications.

Conversions can be applied to the nth argument after the format-string in the argument-list, rather than to the next unused argument. In this case, the conversion character % is replaced by the sequence %n$, where n is a decimal integer in the range [1, {NL_ARGMAX}], (NL_ARGMAX is defined in <limits.h>), giving the position of the argument in the argument-list. This feature provides for the definition of format strings that select arguments in an order appropriate to specific languages; it is useful in message catalogs because it allows the translated text to have the message inserts in any order.

In format strings containing the %n$ form of conversion specifications, numbered arguments in the argument-list can be referenced from the format-string as many times as required.

A format specification has the following form:

Each field of the format specification is a single, or double character, or number signifying a particular format option. The type character, which appears after the last optional format field, determines whether the associated argument is interpreted as a character, a string, a number, or pointer. The simplest format specification contains only the percent sign and a type character (for example, %s).

In format strings containing the %n$ form of a conversion specification, a field width or precision may be indicated by the sequence *m$, where m is a decimal integer in the range [1, {NL_ARGMAX}] giving the position in the argument-list (after the format argument) of an integer argument containing the field width or precision. For example:

>     printf("%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec);

The format-string can contain either numbered argument specifications (that is, %n$ and *m$), or unnumbered argument specifications (that is, % and *), but normally not both. The only exception to this is that %% can be mixed with the %n$ form. The results of mixing numbered and unnumbered argument specifications in a format-string string are undefined. When numbered argument specifications are used, specifying the Nth argument requires that all the leading arguments, from the first to the (N-1)th, are specified in the format string.

When the %n$ form of a conversion specification is used, the flags are specified following the "n$".

The following optional fields control other aspects of the formatting:

Field | Description
Flags | Justification of output and printing of signs, blanks, decimal points, octal, and hexadecimal prefixes, and the semantics for wchar_t precision unit.
Width | Minimum number of characters (bytes) output.
Precision | Maximum number of characters (bytes) printed for all or part of the output field, or minimum number of digits printed for integer values.
h, l, L, 11 | Size of argument expected.
h | A prefix with the integer types d, i, o, u, x, X, and n that specifies that the argument is short int or unsigned short int.
L | A prefix with e, E, f, g, or G types that specifies that the argument is long double.
l | A prefix with d, i, o, u, x, X, and n types that specifies that the argument is a long int or unsigned long int.
ll | A prefix with d, i, o, u, x, X, and n types that specifies that the argument is a long long int or unsigned long long int.

Each field of the format specification is discussed in detail below. If a percent sign (%) is followed by a character that has no meaning as a format field, the character is simply copied to stdout. For example, to print a percent sign character, use %%.

In extended mode, on OS/2 and Windows, printf also converts floating-point values of NaN and infinity to the strings "NAN" or "nan" and "INFINITY" or "infinity". The case and sign of the string is determined by the format specifiers. See for more information on infinity and NaN values.

If you specify a null string for the %s or %ls format specifier, printf prints (null). (In previous releases of the C/C++ run-time library, printf produced no output for a null string.)

Format Specification -- Types
The type characters and their meanings are given in the following table:

Type | Argument | Output Format
d, i | Integer | Signed decimal integer.
u | Integer | Unsigned decimal integer.
o | Integer | Unsigned octal integer.
x | Integer | Unsigned hexadecimal integer, using abcdef.
X | Integer | Unsigned hexadecimal integer, using ABCDEF.
f | Double | Signed value having the form [-]dddd.dddd, where dddd is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number. The number of digits after the decimal point is equal to the requested precision. NaN and infinity values are printed in lowercase (nan and infinity).
F | Double | In extended mode (/Se option), identical to the f format except that NaN and infinity values are printed in uppercase (NAN and INFINITY). In modes other than extended, F is treated like any other character not included in this table.
e | Double | Signed value having the form [-]d.dddde[sign]ddd, where d is a single-decimal digit, dddd is one or more decimal digits, ddd is 2 or 3 decimal digits, and sign is + or -.
E | Double | Identical to the e format except that E introduces the exponent instead of e.
g | Double | Signed value printed in f or e format. The e format is used only when the exponent of the value is less than -4 or greater than precision. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it.
G | Double | Identical to the g format except that E introduces the exponent (where appropriate) instead of e.
c | Character | Single character.
lc or C (See Note below.) | Wide character | Multibyte character (converted as if by a call to wctomb), and character is printed out.
s | String | Characters printed up to the first null character (\0) or until precision is reached. If you specify a null string, "(null)" is printed.
ls or S (See Note below.) | Wide-character string | Multibyte characters, as if by a call to wcstombs, and these characters are printed out. If you specify a null string, "(null)" is printed.
n | Pointer to integer | Number of characters successfully written so far to the stream or buffer; this value is stored in the integer whose address is given as the argument.
p | Pointer | Pointer to void converted to a sequence of printable characters.

Note: IBM C and C++ Compilers supports the type characters %lc and %ls in accordance with ANSI 93, and supports %C and %S to comply with XPG4.

Format Specification -- Flags
The flag characters and their meanings are as follows (notice that more than one flag can appear in a format specification):

Flag | Meaning | Default
- | Left-justify the result within the field width. | Right-justify.
+ | Prefix the output value with a sign (+ or -) if the output value is of a signed type. | Sign appears only for negative signed values (-).
blank (' ') | Prefix the output value with a blank if the output value is signed and positive. The + flag overrides the blank flag if both appear, and a positive signed value will be output with a sign. | No blank.
# | When used with the o, x, or X formats, the # flag prefixes any nonzero output value with 0, 0x, 0X, respectively. | No prefix.
When used with the f, F, e, or E formats, the # flag forces the output value to contain a decimal point in all cases. | Decimal point appears only if digits follow it.
When used with the g or G formats, the # flag forces the output valued to contain a decimal point in all cases and prevents the truncation of trailing zeros. | Decimal point appears only if digits follow it; trailing zeros are truncated.
When used with the 1s format, the # flag causes precision to be measured in wchar_t characters. | Precision indicates the maximum number of bytes to be output.
0 | When used with the d, i, o, u, x, X, e, E, f, F, g, or G formats, the 0 flag causes leading 0's to pad the output to the field width. The 0 flag is ignored if precision is specified for an integer or if the - flag is specified. | Space padding.
' | Formats with the thousands grouping character of the appropriate locale for the decimal conversions (%i, %d, %u, %f, %g, or %G). | No grouping character.

The # flag should not be used with c, lc, d, i, u, s, or p types.

Format Specification -- Width
Width is a nonnegative decimal integer controlling the minimum number of characters printed. If the number of characters in the output value is less than the specified width, blanks are added on the left or the right (depending on whether the - flag is specified) until the minimum width is reached.

Width never causes a value to be truncated; if the number of characters in the output value is greater than the specified width, or width is not given, all characters of the value are printed (subject to the precision specification).

For the ls and S types, width is specified in bytes. If the number of bytes in the output value is less than the specified width, single-byte blanks are added on the left or the right (depending on whether the - flag is specified) until the minimum width is reached.

The width specification can be an asterisk (*), in which case an argument from the argument list supplies the value. The width argument must precede the value being formatted in the argument list.

Format Specification -- Precision
Precision is a nonnegative decimal integer preceded by a period, which specifies the number of characters to be printed or the number of decimal places. Unlike the width specification, the precision can cause truncation of the output value or rounding of a floating-point value.

The precision specification can be an asterisk (*), in which case an argument from the argument list supplies the value. The precision argument must precede the value being formatted in the argument list.

The interpretation of the precision value and the default when the precision is omitted depend upon the type, as shown in the following table:

Type | Meaning | Default
--- | --- | ---
i d u o x X | Precision specifies the minimum number of digits to be printed. If the number of digits in the argument is less than precision, the output value is padded on the left with zeros. The value is not truncated when the number of digits exceeds precision. | If precision is 0 or omitted entirely, or if the period (.) appears without a number following it, the precision is set to 1.
f F e E | Precision specifies the number of digits to be printed after the decimal point. The last digit printed is rounded. | Default precision for f, e and E is six. Default precision for D(n,p) is p. If precision is 0 or the period appears without a number following it, no decimal point is printed.
g G | Precision specifies the maximum number of significant digits printed. | All significant digits are printed.
c | No effect. | The character is printed.
lc or C | No effect. | The wchar_t character is printed.
s | Precision specifies the maximum number of characters to be printed. Characters in excess of precision are not printed. | Characters are printed until a null character is encountered.
ls or S | Precision specifies the maximum number of bytes to be printed. Bytes in excess of precision are not printed; however, multibyte integrity is always preserved. | wchar_t characters are printed until a null character is encountered.

Format Specification - h, l, L, ll
The h, l, L, and ll characters specify the size of the expected argument. Their meanings are as follows:

h | A prefix with the integer types d, i, o, u, x, X, and n that specifies that the argument is short int or unsigned short int.
l | A prefix with d, i, o, u, x, X, and n types that specifies that the argument is a long int or unsigned long int.
L | A prefix with e, E, f, g, or G types that specifies that the argument is long double.
ll | A prefix with d, i, o, u, x, X, and n types that specifies that the argument is long long int or unsigned long long int.

Return Value
The printf function returns the number of bytes printed.

Example
This example prints data in a variety of formats.

    #include <stdio.h>
    #include <wchar.h>

    int main(void)
    {
       char ch = 'h', *string = "computer";
       int count = 234, hex = 0x10, oct = 010, dec = 10;
       double fp = 251.7366;
       wchar_t wc = (wchar_t)0x0058;
       wchar_t ws[4];

       ws[0] = (wchar_t)0x0041;
       ws[1] = (wchar_t)0x0042;
       ws[2] = (wchar_t)0x0043;
       ws[3] = (wchar_t)0x0000;

       printf("%d   %+d    %06d     %X    %x     %o\n\n",
              count, count, count, count, count);

       printf("1234567890123%n4567890123456789\n\n", &count);
       printf("Value of count should be 13; count = %d\n\n", count);
       printf("%10c%5c\n\n", ch, ch);
       printf("%25s\n%25.4s\n\n", string, string);
       printf("%f    %.2f    %e    %E\n\n", fp, fp, fp, fp);
       printf("%i    %i     %i\n\n", hex, oct, dec);
       printf("%C    %S\n\n",wc,ws);
       printf("%2$C     %1$2S\n\n",ws,wc);

       return 0;

       /****************************************************************
          The output should be:

          234   +234    000234     EA    ea     352

          12345678901234567890123456789

          Value of count should be 13; count = 13

                   h    h

                           computer
                               comp

          251.736600    251.74    2.517366e+02    2.517366E+02

          16    8     10

          X     ABC

          X     AB
       ****************************************************************/
    }

_cprintf -- Print Characters to Screen
fprintf -- Write Formatted Data to a Stream
fscanf -- Read Data from a Stream
scanf -- Read Data
sprintf -- Print Formatted Data to Buffer
sscanf -- Read Data from Buffer
swprintf -- Format and Write Wide Characters to Buffer
vfprintf -- Print Argument Data to Stream
vprintf -- Print Argument Data
vsprintf -- Print Argument Data to Buffer
vswprintf -- Format and Write Wide Characters to Buffer
<limits.h>
<stdio.h>