C Programming/stdio.h/printf



Printf functions (which stands for "print formatted") are a class of functions typically associated with some types of programming languages. They accept a string parameter called the format string, which specifies a method for rendering an arbitrary number of varied data type parameter(s) into a string. This string is then by default printed on the standard output stream, but variants exist that perform other tasks with the result. Characters in the format string are usually copied literally into the function's output, with the other parameters being rendered into the resulting text at points marked by format specifiers, which are typically introduced by a % character.

Timeline
Many programming languages implement a   function, to output a formatted string. It originated from the C programming language, where it has a prototype similar to the following: The string constant  provides a description of the output, with placeholders marked by "%" escape characters, to specify both the relative location and the type of output that the function should produce. The return value yields the number of printed characters.

Fortran, COBOL
Fortran's variadic  statement references a non-executable   statement. will print the following ( after advancing to a new line, because of the leading blank character if directed to a printing device) :

COBOL provides formatting via hierarchical data structure specification: ...

1960s: BCPL, ALGOL 68, Multics PL/I
C's variadic  has its origins in BCPL's   function.

ALGOL 68 Draft and Final report had the functions  and , subsequently these were revised out of the original language and replaced with the now more familiar   and. printf(($"Color "g", number1 "6d,", number2 "4zd,", hex "16r2d,", float "-d.2d,", unsigned value"-3d"."l$, "red", 123456, 89, BIN 255, 3.14, 250));

Multics has a standard function called  with a wide variety of control codes. It was based on a machine-language facility from Multics's BOS (Bootstrap Operating System).

1970s: C, Lisp
will print the following line (including new-line character, \n): Color red, number1 123456, number2 00089, hex ff, float 3.14, unsigned value 250.

The  function returns the number of characters printed, or a negative value if an output error occurs.

Common Lisp has the  function.

prints  on the standard output stream. If the first argument is, format returns the string to its caller. The first argument can also be any output stream. was introduced into ZetaLisp at MIT in 1978, based on the Multics, and was later adopted into the Common Lisp standard.

1980s: Perl, Shell
Perl also has a  function. Common Lisp has a format function which acts according to the same principles as, but uses different characters for output conversion. The GLib library contains, an implementation of.

Some Unix systems have a  program for use in shell scripts. This can be used instead of echo in situations where the latter is not portable. For example: may be rewritten portably as:

1990s: PHP, Python
1991: Python's  operator harkens to  's syntax when interpolating the contents of a tuple. This operator can, for example, be used with the  function:

Version 2.6 of Python included the  which is preferred to the obsolete   which may go away in future versions of Python:

1995: PHP also has the  function, with the same specifications and usage as that in C/C++. MATLAB does not have, but does have its two extensions   and   which use the same formatting strings. returns a formatted string instead of producing a visual output.

2000s: Java
2004: Java supported  from version 1.5 onwards as a member of the  class, giving it the functionality of both the   and fprintf functions. At the same time -like functionality was added to the   class by adding the   method. Unlike most other implementations, Java's implementation of  throws an exception on encountering a malformed format string.

Related functions
The ANSI C standard specifies a number of variations of printf for situations where the output stream is not the default, where the parameter list is in a different form, where the output is targeting memory rather than a file descriptor, and so on. The printf function itself is often merely a wrapper, with defaults, around one of these:

fprintf
  enables printf output to be written to any file. Programmers frequently use it to print errors, by writing to the standard error device, but it can operate with any file opened with the  (or  ) function.

sprintf
  prints to a string ( array) instead of standard output. Users of  must ensure, via calculation or via a guard page, that the resulting string will not be larger than the memory allocated for str. Failure to ensure this can allow a buffer overflow to occur.

In higher-level languages such as PHP the  function does not have the   argument. Instead, it returns the formatted output string. The prototype in PHP is like this:

Buffer safety and sprintf
In ISO C99,   was introduced as an alternative to   that can help avoid the risk of a buffer overflow:

is guaranteed not to write more than size bytes into str, so use of it can help avoid the risk of a buffer overflow, as in the following code fragment: If username in the above example causes result to exceed 49 bytes in length, the function will limit the string that gets saved in buf by cutting off final bytes (truncating). The null terminator will always be written to the 50th location so the result is always null terminated. Additionally, the return code of  indicates how many bytes (not counting the null) the function would have written to the string had enough space existed. Systems can use this information to allocate a new (larger) buffer if they require the whole string.

A number of  implementations deviated from the above description, in particular many Windows libraries, glibc before version 2.0.6, and Solaris. The most common mistake was returning -1 on truncation rather than the length needed. More troublesome were implementations that did not write the null terminator on truncation, or returned size-1 (making it impossible to detect truncation). These deviations make writing portable safe code using  harder than it should be.

Another safe  alternative is   which is a GNU extension:

automatically allocates enough memory to hold the final string. It sets  to a pointer to the resulting string, or to an undefined value if an error occurred (glibc is notable in being the only implementation that doesn't always set   to NULL on error). The programmer using  has the responsibility of freeing the allocated memory after use. Though not part of any standard,  comes in the C libraries of several operating systems (including OpenBSD, FreeBSD, and NetBSD) and on other platforms in the libiberty library.

GLib provides yet another safe alternative:, which allocates enough memory, but, unlike  , returns the resulting string as its return value rather than via the first argument.

C++ alternatives to sprintf for numeric conversion
The standard method for string formatting and the conversion of other types to strings in C++ is iostream. Unlike printf, the iostream standard library is type-safe and extensible.

A common programming task is to convert a numeric type into a string (char buffer). The  family, while useful, may be overkill for such a simple task. In addition many programs using these are not designed to handle the variations in output when the locale changes.

A number of alternative means in C/C++ have been developed:
 * Boost::lexical_cast
 * Boost::format
 * Loki::SafeFormat
 * itoa (nonstandard)
 * std::to_string (C++11)
 * C++ Format (cppformat)

vprintf, vfprintf, vsprintf, vsnprintf, and vasprintf
These are analogous to the above functions without the vs, except that they use variable argument lists. These functions offer the ability for programmers to essentially create their own printf variants. For instance, a programmer could write a function

which would use the  macro to obtain a   variable from the extra parameters, print a message on the standard error device using , clean up after the   variable with the   macro, and finally perform the necessary tasks to cleanly shut down the program.

Another common application of these functions is to write a custom printf that prints to a different target than a file. For instance, a graphical library might provide a printf-like function with X and Y coordinates:

This would work by temporarily saving the string to a private buffer using  or.

Format placeholders
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 ". To denote that we want the integer for the age to be shown immediately after that message, we may use the format string: "Your age is %d."

The syntax for a format placeholder is


 * Parameter can be omitted or can be:
 * {| class="wikitable"

! Character ! Description "17 0x11; 16 0x10"
 * 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. This is a POSIX extension and not in C99. Example:  produces
 * 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. This is a POSIX extension and not in C99. Example:  produces
 * 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. This is a POSIX extension and not in C99. Example:  produces
 * }


 * Flags can be zero or more (in any order) of:
 * {| class="wikitable"

! Character ! Description
 * (minus)
 * Left-align the output of this placeholder (the default is to right-align the output).
 * (plus)
 * Prepends a plus for positive signed-numeric types. positive = ' ', negative = ' '. (the default doesn't prepend anything in front of positive numbers).
 * (space)
 * Prepends a space for positive signed-numeric types. positive = ' ', negative = ' '. This flag is ignored if the '+' flag exists. (the default doesn't prepend anything in front of positive numbers).
 * (zero)
 * Prepends zeros for numbers when the width option is specified. (the default prepends spaces).
 * Prepends a space for positive signed-numeric types. positive = ' ', negative = ' '. This flag is ignored if the '+' flag exists. (the default doesn't prepend anything in front of positive numbers).
 * (zero)
 * Prepends zeros for numbers when the width option is specified. (the default prepends spaces).
 * Prepends zeros for numbers when the width option is specified. (the default prepends spaces).

Example:  produces " ", while   produces in " ".
 * (hash)
 * Alternate form. For ' ' and ' ', trailing zeros are not removed. For ' ', ' ', ' ', ' ', ' ', ' ', the output always contains a decimal point. For ' ', ' ', ' ', or ' ', ' ', ' ', respectively, is prepended to non-zero numbers.
 * }
 * }


 * Width 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. A leading zero in the width value 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.
 * Precision 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.


 * Length can be omitted or be any of:
 * {| class="wikitable"

! Character ! Description
 * For integer types, causes  to expect an   sized integer argument which was promoted from a.
 * For integer types, causes  to expect an   sized integer argument which was promoted from a.
 * For integer types, causes  to expect a   sized integer argument.
 * For integer types, causes  to expect a   sized integer argument.
 * For floating point types, causes  to expect a   argument.
 * For integer types, causes  to expect a   sized integer argument.
 * For integer types, causes  to expect a   sized integer argument.
 * For integer types, causes  to expect a   sized integer argument.
 * }
 * For integer types, causes  to expect a   sized integer argument.
 * For floating point types, causes  to expect a   argument.
 * For integer types, causes  to expect a   sized integer argument.
 * For integer types, causes  to expect a   sized integer argument.
 * For integer types, causes  to expect a   sized integer argument.
 * }
 * For integer types, causes  to expect a   sized integer argument.
 * For integer types, causes  to expect a   sized integer argument.
 * For integer types, causes  to expect a   sized integer argument.
 * }
 * For integer types, causes  to expect a   sized integer argument.
 * For integer types, causes  to expect a   sized integer argument.
 * }
 * For integer types, causes  to expect a   sized integer argument.
 * }
 * }

Additionally, several platform-specific length options came to exist prior to widespread use of the ISO C99 extensions:
 * {| class="wikitable"

! Characters ! Description
 * For signed integer types, causes  to expect   sized integer argument; for unsigned integer types, causes   to expect   sized integer argument. Commonly found in Win32/Win64 platforms.
 * For integer types, causes  to expect a 32-bit (double word) integer argument.  Commonly found in Win32/Win64 platforms.
 * For integer types, causes  to expect a 64-bit (quad word) integer argument.  Commonly found in Win32/Win64 platforms.
 * For integer types, causes  to expect a 64-bit (quad word) integer argument.  Commonly found in BSD platforms.
 * }
 * For integer types, causes  to expect a 32-bit (double word) integer argument.  Commonly found in Win32/Win64 platforms.
 * For integer types, causes  to expect a 64-bit (quad word) integer argument.  Commonly found in Win32/Win64 platforms.
 * For integer types, causes  to expect a 64-bit (quad word) integer argument.  Commonly found in BSD platforms.
 * }
 * For integer types, causes  to expect a 64-bit (quad word) integer argument.  Commonly found in BSD platforms.
 * }
 * For integer types, causes  to expect a 64-bit (quad word) integer argument.  Commonly found in BSD platforms.
 * }

ISO C99 includes the  header file that includes a number of macros for use in platform-independent   coding. Example macros include:
 * {| class="wikitable"

! Characters ! Description
 * Typically equivalent to  (Win32/Win64) or
 * Typically equivalent to  (Win32/Win64),   (32-bit platforms) or   (64-bit platforms)
 * Typically equivalent to  (Win32/Win64) or
 * Typically equivalent to  (Win32/Win64),   (32-bit platforms) or   (64-bit platforms)
 * Typically equivalent to  (Win32/Win64) or
 * Typically equivalent to  (Win32/Win64),   (32-bit platforms) or   (64-bit platforms)
 * Typically equivalent to  (Win32/Win64),   (32-bit platforms) or   (64-bit platforms)
 * }
 * Typically equivalent to  (Win32/Win64) or
 * Typically equivalent to  (Win32/Win64),   (32-bit platforms) or   (64-bit platforms)
 * Typically equivalent to  (Win32/Win64) or
 * Typically equivalent to  (Win32/Win64),   (32-bit platforms) or   (64-bit platforms)
 * Typically equivalent to  (Win32/Win64),   (32-bit platforms) or   (64-bit platforms)
 * }
 * Typically equivalent to  (Win32/Win64) or
 * Typically equivalent to  (Win32/Win64),   (32-bit platforms) or   (64-bit platforms)
 * Typically equivalent to  (Win32/Win64),   (32-bit platforms) or   (64-bit platforms)
 * }
 * Typically equivalent to  (Win32/Win64),   (32-bit platforms) or   (64-bit platforms)
 * }
 * Typically equivalent to  (Win32/Win64),   (32-bit platforms) or   (64-bit platforms)
 * }


 * Type can be any of:
 * {| class="wikitable"

! Character ! Description
 * as a signed decimal number. ' ' and ' ' are synonymous for output, but are different when used with  for input.
 * Print decimal.
 * 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').
 * value in standard form ([-]d.ddd e[+/-]ddd). 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   function.
 * 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.
 * as a hexadecimal number. 'x' uses lower-case letters and 'X' uses upper-case.
 * in octal.
 * null-terminated string.
 * (character).
 * (pointer to void) in an implementation-defined format.
 * Print nothing, but write number of characters successfully written so far into an integer pointer parameter.
 * a literal '%' character (this type doesn't accept any flags, width, precision or length).
 * }
 * 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.
 * as a hexadecimal number. 'x' uses lower-case letters and 'X' uses upper-case.
 * in octal.
 * null-terminated string.
 * (character).
 * (pointer to void) in an implementation-defined format.
 * Print nothing, but write number of characters successfully written so far into an integer pointer parameter.
 * a literal '%' character (this type doesn't accept any flags, width, precision or length).
 * }
 * null-terminated string.
 * (character).
 * (pointer to void) in an implementation-defined format.
 * Print nothing, but write number of characters successfully written so far into an integer pointer parameter.
 * a literal '%' character (this type doesn't accept any flags, width, precision or length).
 * }
 * (pointer to void) in an implementation-defined format.
 * Print nothing, but write number of characters successfully written so far into an integer pointer parameter.
 * a literal '%' character (this type doesn't accept any flags, width, precision or length).
 * }
 * Print nothing, but write number of characters successfully written so far into an integer pointer parameter.
 * a literal '%' character (this type doesn't accept any flags, width, precision or length).
 * }
 * a literal '%' character (this type doesn't accept any flags, width, precision or length).
 * }

The width and precision formatting parameters may be omitted, or they can be a fixed number embedded in the format string, or passed as another function argument when indicated by an asterisk "*" in the format string. For example  will result in   being printed, with a total width of 5 characters, and   will result in "abc" being printed.

If the syntax of a conversion specification is invalid, behavior is undefined, and can cause program termination. 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 also undefined. Excess arguments are ignored. In a number of cases, the undefined behavior has led to "Format string attack" security vulnerabilities.

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  or  ). GCC will also warn about user-defined printf-style functions if the non-standard "format" __attribute__ is applied to the function.

Risks of using field width versus explicit delimiters in tabular output
Using only field widths to provide for tabulation, as with a format like " " 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 " " 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.

Custom format placeholders
There are a few implementations of -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. 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, and can work with static format checkers.

Some applications (like the Apache HTTP Server) include their own -like function, and embed extensions into it. However these all tend to have the same problems that  has.

Most non-C languages that have a -like function work around the lack of this feature by just using the " " format and converting the object to a string representation. C++ offers a notable exception, in that it has a  function inherited from its C history, but also has a completely different mechanism that is preferred.

Programming languages with printf

 * AMPL
 * awk
 * Bourne shell (sh) and derivatives such as Korn shell (ksh), Bourne again shell (bash), or Z shell (zsh)
 * C
 * C++ (also provides overloaded shift operators and manipulators as an alternative for formatted output - see iostream and iomanip)
 * Objective-C
 * Clojure
 * D
 * F#
 * GNU MathProg
 * GNU Octave
 * Go
 * Haskell
 * Java (since version 1.5)
 * Maple
 * Mathematica
 * MATLAB
 * Mythryl
 * Objective Caml
 * PHP
 * Perl
 * Python (using the % operator)
 * R
 * Ruby
 * Vala (via  and  )