This article needs additional citations for verification. (February 2015)
The printf format string is a control parameter used by a class of functions in the input/output libraries of C and many other programming languages. The string is written in a simple template language: characters are usually copied literally into the function's output, but format specifiers, which start with a
% character, indicate the location and method to translate a piece of data (such as a number) to characters.
"printf" is the name of one of the main C output functions, and stands for "print formatted". printf format strings are complementary to scanf format strings, which provide formatted input (lexing aka. parsing). In both cases these provide simple functionality and fixed format compared to more sophisticated and flexible template engines or lexers/parsers, but are sufficient for many purposes.
Many languages other than C copy the printf format string syntax closely or exactly in their own I/O functions.
Mismatches between the format specifiers and type of the data can cause crashes and other vulnerabilities. The format string itself is very often a string literal, which allows static analysis of the function call. However, it can also be the value of a variable, which allows for dynamic formatting but also a security vulnerability known as an uncontrolled format string exploit.
Early programming languages such as Fortran used special statements with completely different syntax from other calculations to build formatting descriptions. In this example, the format is specified on line 601, and the WRITE command refers to it by line number:
WRITE OUTPUT TAPE 6, 601, IA, IB, IC, AREA 601 FORMAT (4H A= ,I5,5H B= ,I5,5H C= ,I5, & 8H AREA= ,F10.2, 13H SQUARE UNITS)
printf(($"Color "g", number1 "6d,", number2 "4zd,", hex "16r2d,", float "-d.2d,", unsigned value"-3d"."l$, "red", 123456, 89, BIN 255, 3.14, 250));
But using the normal function calls and data types simplifies the language and compiler, and allows the implementation of the input/output to be written in the same language. These advantages outweigh the disadvantages (such as a complete lack of type safety in many instances) and in most newer languages I/O is not part of the syntax.
printf has its origins in BCPL's
writef function (1966). In comparison to
*N is a BCPL language escape sequence representing a newline character (for which C uses the escape sequence
\n) and the order of the format specification's field width and type is reversed in
WRITEF("%I2-QUEENS PROBLEM HAS %I5 SOLUTIONS*N", NUMQUEENS, COUNT)
Formatting takes place via placeholders within the format string. For example, if a program wanted to print out a person's age, it could present the output by prefixing it with "Your age is ", and using the signed decimal specifier character
d to denote that we want the integer for the age to be shown immediately after that message, we may use the format string:
printf("Your age is %d", age);
The syntax for a format placeholder is
|n$||n is the number of the parameter to display using this format specifier, allowing the parameters provided to be output multiple times, using varying format specifiers or in different orders. If any single placeholder specifies a parameter, all the rest of the placeholders MUST also specify a parameter.|
This feature mainly sees its use in localization, where the order of occurrence of parameters vary due to the language-dependent convention.
On the non-POSIX Microsoft Windows, support for this feature is placed in a separate printf_p function.
The Flags field can be zero or more (in any order) of:
|Left-align the output of this placeholder. (The default is to right-align the output.)|
|Prepends a plus for positive signed-numeric types. positive = +, negative = -.|
(The default doesn't prepend anything in front of positive numbers.)
|Prepends a space for positive signed-numeric types. positive = |
(The default doesn't prepend anything in front of positive numbers.)
|When the 'width' option is specified, prepends zeros for numeric types. (The default prepends spaces.)|
|The integer or exponent of a decimal has the thousands grouping separator applied.|
For g and G types, trailing zeros are not removed.
For f, F, e, E, g, G types, the output always contains a decimal point.
For o, x, X types, the text 0, 0x, 0X, respectively, is prepended to non-zero numbers.
The Width field specifies a minimum number of characters to output, and is typically used to pad fixed-width fields in tabulated output, where the fields would otherwise be smaller, although it does not cause truncation of oversized fields.
The width field may be omitted, or a numeric integer value, or a dynamic value when passed as another argument when indicated by an asterisk *. For example,
printf("%*d", 5, 10) will result in
10 being printed, with a total width of 5 characters.
Though not part of the width field, a leading zero is interpreted as the zero-padding flag mentioned above, and a negative value is treated as the positive value in conjunction with the left-alignment - flag also mentioned above.
The Precision field usually specifies a maximum limit on the output, depending on the particular formatting type. For floating point numeric types, it specifies the number of digits to the right of the decimal point that the output should be rounded. For the string type, it limits the number of characters that should be output, after which the string is truncated.
The precision field may be omitted, or a numeric integer value, or a dynamic value when passed as another argument when indicated by an asterisk *. For example,
printf("%.*s", 3, "abcdef") will result in
abc being printed.
The Length field can be omitted or be any of:
|hh||For integer types, causes printf to expect an int-sized integer argument which was promoted from a char.|
|h||For integer types, causes printf to expect an int-sized integer argument which was promoted from a short.|
|l||For integer types, causes printf to expect a long-sized integer argument.
For floating point types, this is ignored. float arguments are always promoted to double when used in a varargs call.
|ll||For integer types, causes printf to expect a long long-sized integer argument.|
|L||For floating point types, causes printf to expect a long double argument.|
|z||For integer types, causes printf to expect a size_t-sized integer argument.|
|j||For integer types, causes printf to expect a intmax_t-sized integer argument.|
|t||For integer types, causes printf to expect a ptrdiff_t-sized integer argument.|
Additionally, several platform-specific length options came to exist prior to widespread use of the ISO C99 extensions:
|I||For signed integer types, causes printf to expect ptrdiff_t-sized integer argument; for unsigned integer types, causes printf to expect size_t-sized integer argument. Commonly found in Win32/Win64 platforms.|
|I32||For integer types, causes printf to expect a 32-bit (double word) integer argument. Commonly found in Win32/Win64 platforms.|
|I64||For integer types, causes printf to expect a 64-bit (quad word) integer argument. Commonly found in Win32/Win64 platforms.|
|q||For integer types, causes printf to expect a 64-bit (quad word) integer argument. Commonly found in BSD platforms.|
ISO C99 includes the
inttypes.h header file that includes a number of macros for use in platform-independent
printf coding. These must be outside double-quotes, e.g.
printf("%" PRId64 "\n", t);
Example macros include:
|PRId32||Typically equivalent to I32d (Win32/Win64) or d|
|PRId64||Typically equivalent to I64d (Win32/Win64), lld (32-bit platforms) or ld (64-bit platforms)|
|PRIi32||Typically equivalent to I32i (Win32/Win64) or i|
|PRIi64||Typically equivalent to I64i (Win32/Win64), lli (32-bit platforms) or li (64-bit platforms)|
|PRIu32||Typically equivalent to I32u (Win32/Win64) or u|
|PRIu64||Typically equivalent to I64u (Win32/Win64), llu (32-bit platforms) or lu (64-bit platforms)|
|PRIx32||Typically equivalent to I32x (Win32/Win64) or x|
|PRIx64||Typically equivalent to I64x (Win32/Win64), llx (32-bit platforms) or lx (64-bit platforms)|
The Type field can be any of:
|%||Prints a literal % character (this type doesn't accept any flags, width, precision, length fields).|
|d, i||int as a signed integer. %d and %i are synonymous for output, but are different when used with |
|u||Print decimal unsigned int.|
|f, F||double in normal (fixed-point) notation. f and F only differs in how the strings for an infinite number or NaN are printed (inf, infinity and nan for f; INF, INFINITY and NAN for F).|
|e, E||double value in standard form (d.ddde±dd). An E conversion uses the letter E (rather than e) to introduce the exponent. The exponent always contains at least two digits; if the value is zero, the exponent is 00. In Windows, the exponent contains three digits by default, e.g. 1.5e002, but this can be altered by Microsoft-specific |
|g, G||double in either normal or exponential notation, whichever is more appropriate for its magnitude. g uses lower-case letters, G uses upper-case letters. This type differs slightly from fixed-point notation in that insignificant zeroes to the right of the decimal point are not included. Also, the decimal point is not included on whole numbers.|
|x, X||unsigned int as a hexadecimal number. x uses lower-case letters and X uses upper-case.|
|o||unsigned int in octal.|
|p||void* (pointer to void) in an implementation-defined format.|
|a, A||double in hexadecimal notation, starting with 0x or 0X. a uses lower-case letters, A uses upper-case letters. (C++11 iostreams have a hexfloat that works the same).|
|n||Print nothing, but writes the number of characters written so far into an integer pointer parameter.|
In Java this prints a newline.
There are a few implementations of
printf-like functions that allow extensions to the escape-character-based mini-language, thus allowing the programmer to have a specific formatting function for non-builtin types. One of the most well-known is the (now deprecated) glibc's
register_printf_function(). However, it is rarely used due to the fact that it conflicts with static format string checking. Another is Vstr custom formatters, which allows adding multi-character format names.
Some applications (like the Apache HTTP Server) include their own
printf-like function, and embed extensions into it. However these all tend to have the same problems that
The Linux kernel
printk function supports a number of ways to display kernel structures using the generic
%p specification, by appending additional format characters. For example,
%pI4 prints an IPv4 address in dotted-decimal form. This allows static format string checking (of the
%p portion) at the expense of full compatibility with normal printf.
Most languages that have a
printf-like function work around the lack of this feature by just using the
%s format and converting the object to a string representation.
If there are too few function arguments provided to supply values for all the conversion specifications in the template string, or if the arguments are not of the correct types, the results are undefined, may crash. Implementations are inconsistent about whether syntax errors in the string consume an argument and what type of argument they consume. Excess arguments are ignored. In a number of cases, the undefined behavior has led to "Format string attack" security vulnerabilities. In most C or C++ calling conventions arguments may be passed on the stack, which means in the case of too few arguments printf will read past the end of the current stackframe, thus allowing the attacker to read the stack.
Some compilers, like the GNU Compiler Collection, will statically check the format strings of printf-like functions and warn about problems (when using the flags
-Wformat). GCC will also warn about user-defined printf-style functions if the non-standard "format"
__attribute__ is applied to the function.
Using only field widths to provide for tabulation, as with a format like
%8d%8d%8d for three integers in three 8-character columns, will not guarantee that field separation will be retained if large numbers occur in the data. Loss of field separation can easily lead to corrupt output. In systems which encourage the use of programs as building blocks in scripts, such corrupt data can often be forwarded into and corrupt further processing, regardless of whether the original programmer expected the output would only be read by human eyes. Such problems can be eliminated by including explicit delimiters, even spaces, in all tabular output formats. Simply changing the dangerous example from before to
%7d %7d %7d addresses this, formatting identically until numbers become larger, but then explicitly preventing them from becoming merged on output due to the explicitly included spaces. Similar strategies apply to string data.
Although an outputting function on the surface,
printf allows for write to a memory location specified by an argument via
%n. This functionality is occasionally used as a part of more elaborate format string attacks.
printfutility command, sometimes built in to the shell, such as with some implementations of the KornShell (ksh), Bourne again shell (bash), or Z shell (zsh). These commands usually interpret C escapes in the format string.
printk(print kernel messages)