printf

Writes formatted output to stdout.

Defined in header <stdio.h>

Syntax

#include <stdio.h>
int printf(const char *format[, argument, ...]);

Portability

Remarks

printf accepts a series of arguments, applies to each a format specifier contained in the format string given by format, and outputs the formatted data to stdout. There must be the same number of format specifiers as arguments.

The format string

The format string, present in each of the ...printf function calls, controls how each function will convert, format, and print its arguments. There must be enough arguments for the format; if there are not, the results will be unpredictable and likely disastrous. Excess arguments (more than required by the format) are merely ignored.

The format string is a character string that contains two types of objects — plain characters and conversion specifications:

• Plain characters are simply copied verbatim to the output stream.
• Conversion specifications fetch arguments from the argument list and apply formatting to them.

Format specifiers

...printf format specifiers have the following form:

% [flags] [width] [.prec] [F|N|h|l|L] type

Each conversion specification begins with the percent character (%). After the % come the following, in this order:

• an optional sequence of flag characters, [flags]
• an optional width specifier, [width]
• an optional precision specifier, [.prec]
• an optional input-size modifier, [F|N|h|l|L]
• the conversion-type character, [type]

Optional format string components

These are the general aspects of output formatting controlled by the optional characters, specifiers, and modifiers in the format string:

...printf conversion-type characters

The following table lists the ...printf conversion-type characters, the type of input argument accepted by each, and in what format the output appears.

The information in this table of type characters is based on the assumption that no flag characters, width specifiers, precision specifiers, or input-size modifiers were included in the format specifier. To see how the addition of the optional characters and specifiers affects the ...printf output, refer to the tables following this one.

Conventions

Certain conventions accompany some of these specifications, as summarized in the following table:

Note: Infinite floating-point numbers are printed as +INF and −INF. An IEEE Not-a-Number is printed as +NAN or −NAN.

Flag characters

The flag characters are minus (-), plus (+), sharp (#), and blank ( ). They can appear in any order and combination.

Note: Plus (+) takes precedence over blank ( ) if both are given.

Alternate forms

If the # flag is used with a conversion character, it has the following effect on the argument (arg) being converted:

Width specifiers

The width specifier sets the minimum field width for an output value.

Width is specified in one of two ways: directly, through a decimal digit string, or indirectly, through an asterisk (*). If you use an asterisk for the width specifier, the next argument in the call (which must be an int) specifies the minimum output field width.

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 simply expanded to contain the conversion result.

Precision specifiers

A precision specification always begins with a period (.) to separate it from any preceding width specifier. Then, like width, precision is specified either directly through a decimal digit string, or indirectly through an asterisk (*). If you use an asterisk for the precision specifier, the next argument in the call (treated as an int) specifies the precision.

If you use asterisks for the width or the precision, or for both, the width argument must immediately follow the specifiers, followed by the precision argument, then the argument for the data to be converted.

Note: If an explicit precision of zero is specified, and the format specifier for the field is one of the integer formats (that is, d, i, o, u, x), and the value to be printed is 0, no numeric characters will be output for that field (that is, the field will be blank).

Input-size modifier

The input-size modifier character (F, N, h, l, or L) gives the size of the subsequent input argument:

• F = far pointer
• N = near pointer
• h = short int
• l = long
• L = long double

The input-size modifiers (F, N, h, l, and L) affect how the ...printf functions interpret the data type of the corresponding input argument arg. F and N apply only to input args that are pointers (%p, %s, and %n). h, L, and L apply to input args that are numeric (integers and floating-point).

Both F and N reinterpret the input arg. Normally, the arg for a %p, %s, or %n conversion is a pointer of the default size for the memory model. F says "interpret arg as a far pointer." N says "interpret arg as a near pointer."

h, l, and L override the default size of the numeric data input arguments: l and L apply to integer (d, i, o, u, x, X) and floating-point (e, E, f, g, and G) types, while h applies to integer types only. Neither h nor l affect character (c, s) or pointer (p, n) types.

Return value

printf returns the number of bytes output. In the event of error, printf returns EOF.

See also

• cprintf
• ecvt
• fprintf
• fread
• fscanf
• putc
• puts
• putw
• scanf
• sprintf
• vprintf
• vsprintf

Example

#include <stdio.h>
#include <string.h>

#define I 555
#define R 5.5

int main(void)
{
   int i,j,k,l;
   char buf[7];
   char *prefix = buf;
   char tp[20];
   printf("prefix  6d      6o      8x        10.2e        "
          "10.2f\n");
   strcpy(prefix,"%");
   for (i = 0; i < 2; i++) {
      for (j = 0; j < 2; j++)
         for (k = 0; k < 2; k++)
            for (l = 0; l < 2; l++) {
               if (i==0)  strcat(prefix,"-");
               if (j==0)  strcat(prefix,"+");
               if (k==0)  strcat(prefix,"#");
               if (l==0)  strcat(prefix,"0");
               printf("%5s |",prefix);
               strcpy(tp,prefix);
               strcat(tp,"6d |");
               printf(tp,I);
               strcpy(tp,"");
               strcpy(tp,prefix);
               strcat(tp,"6o |");
               printf(tp,I);
               strcpy(tp,"");
               strcpy(tp,prefix);
               strcat(tp,"8x |");
               printf(tp,I);
               strcpy(tp,"");
               strcpy(tp,prefix);
               strcat(tp,"10.2e |");
               printf(tp,R);
               strcpy(tp,prefix);
               strcat(tp,"10.2f |");
               printf(tp,R);
               printf("  \n");
               strcpy(prefix,"%");
            }
      }
   return 0;
}

Program output

prefix  6d      6o      8x        10.2e        10.2f
%-+#0 |+555   |01053  |0x22b    |+5.50e+00  |+5.50      |
 %-+# |+555   |01053  |0x22b    |+5.50e+00  |+5.50      |
 %-+0 |+555   |1053   |22b      |+5.50e+00  |+5.50      |
  %-+ |+555   |1053   |22b      |+5.50e+00  |+5.50      |
 %-#0 |555    |01053  |0x22b    |5.50e+00   |5.50       |
  %-# |555    |01053  |0x22b    |5.50e+00   |5.50       |
  %-0 |555    |1053   |22b      |5.50e+00   |5.50       |
   %- |555    |1053   |22b      |5.50e+00   |5.50       |
 %+#0 |+00555 |001053 |0x00022b |+05.50e+00 |+000005.50 |
  %+# |  +555 | 01053 |   0x22b | +5.50e+00 |     +5.50 |
  %+0 |+00555 |001053 |0000022b |+05.50e+00 |+000005.50 |
   %+ |  +555 |  1053 |     22b | +5.50e+00 |     +5.50 |
  %#0 |000555 |001053 |0x00022b |005.50e+00 |0000005.50 |
   %# |   555 | 01053 |   0x22b |  5.50e+00 |      5.50 |
   %0 |000555 |001053 |0000022b |005.50e+00 |0000005.50 |
    % |   555 |  1053 |     22b |  5.50e+00 |      5.50 |

Differences from modern implementations

Modern references

• cppreference: printf, fprintf, sprintf, snprintf
• POSIX: fprintf, printf, snprintf, sprintf
• Microsoft CRT: printf, _printf_l, wprintf, _wprintf_l
• Microsoft CRT: format specification syntax

Stable link: /3.1/stdio.h/printf/ · short form /3.1/printf/