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 f''ormatted". 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.
History
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)
ALGOL 68 had more function-like
API, but still used special syntax (the delimiters surround special formatting syntax):
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.
C's has its origins in
BCPL
BCPL ("Basic Combined Programming Language") is a procedural, imperative, and structured programming language. Originally intended for writing compilers for other languages, BCPL is no longer in common use. However, its influence is still ...
's function (1966). In comparison to and , is a BCPL ''language'' escape sequence representing a newline character (for which C uses the escape sequence ) 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)
Probably the first copying of the syntax outside the C language was the Unix shell command, which first appeared in
Version 4, as part of the port to C.
Format placeholder specification
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 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);
Syntax
The syntax for a format placeholder is
Parameter field
This is a
POSIX extension and not in
C99. The Parameter field can be omitted or can be:
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.
Flags field
The Flags field can be zero or more (in any order) of:
Width field
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, 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.
Precision field
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, will result in being printed.
Length field
The Length field can be omitted or be any of:
Additionally, several platform-specific length options came to exist prior to widespread use of the ISO C99 extensions:
ISO C99 includes the
inttypes.h
In the C programming language, data types constitute the semantics and characteristics of storage of data elements. They are expressed in the language syntax in form of declarations for memory locations or variables. Data types also determin ...
header file that includes a number of macros for use in platform-independent coding. These must be outside double-quotes, e.g.
Example macros include:
Type field
The Type field can be any of:
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'
However, it is rarely used due to the fact that it conflicts with static format string checking. Another i
Vstr custom formatters which allows adding multi-character format names.
Some applications (like the
Apache HTTP Server
The Apache HTTP Server ( ) is a free and open-source cross-platform web server software, released under the terms of Apache License 2.0. Apache is developed and maintained by an open community of developers under the auspices of the Apache So ...
) include their own -like function, and embed extensions into it. However these all tend to have the same problems that has.
The
Linux kernel
The Linux kernel is a free and open-source, monolithic, modular, multitasking, Unix-like operating system kernel. It was originally authored in 1991 by Linus Torvalds for his i386-based PC, and it was soon adopted as the kernel for the GNU ope ...
printk
function supports a number of ways to display kernel structures using the generic specification, by ''appending'' additional format characters. For example, prints an
IPv4
Internet Protocol version 4 (IPv4) is the fourth version of the Internet Protocol (IP). It is one of the core protocols of standards-based internetworking methods in the Internet and other packet-switched networks. IPv4 was the first version de ...
address in dotted-decimal form. This allows static format string checking (of the portion) at the expense of full compatibility with normal printf.
Most 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.
Vulnerabilities
Invalid conversion specifications
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
Uncontrolled format string is a type of software vulnerability discovered around 1989 that can be used in security exploits. Originally thought harmless, format string exploits can be used to crash a program or to execute harmful code. The problem ...
" 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 or ). GCC will also warn about user-defined printf-style functions if the non-standard "format" is applied to the function.
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:
1234567 1234567 1234567
123 123 123
123 12345678123
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:
1234567 1234567 1234567
123 123 123
123 12345678 123
Similar strategies apply to string data.
Memory write
Although an outputting function on the surface, allows writing to a memory location specified by an argument via . This functionality is occasionally used as a part of more elaborate format-string attacks.
The functionality also makes accidentally
Turing-complete even with a well-formed set of arguments. A game of tic-tac-toe written in the format string is a winner of the 27th
IOCCC.
Programming languages with printf
Not included in this list are languages that use format strings that deviate from the style in this article (such as
AMPL and
Elixir), languages that inherit their implementation from the
JVM or other environment (such as
Clojure and
Scala), and languages that do not have a standard native printf implementation but have external libraries which emulate printf behavior (such as
JavaScript).
*
awk
*
C
**
C++ (also provides
overloaded shift operators and manipulators as an alternative for formatted output – see
iostream and
iomanip)
**
Objective-C
*
D
*
F#
*G (
LabVIEW)
*
GNU MathProg
*
GNU Octave
*
Go
*
Haskell
*
J
*
Java (since version 1.5) and JVM languages
*
Julia (via its Printf standard library
Formatting.jllibrary adds
Python-style general formatting and "c-style part of this package aims to get around the limitation that @sprintf has to take a literal string argument.")
*
Lua
Lua or LUA may refer to:
Science and technology
* Lua (programming language)
* Latvia University of Agriculture
* Last universal ancestor, in evolution
Ethnicity and language
* Lua people, of Laos
* Lawa people, of Thailand sometimes referred t ...
(string.format)
*
Maple
*
MATLAB
*
Max
Max or MAX may refer to:
Animals
* Max (dog) (1983–2013), at one time purported to be the world's oldest living dog
* Max (English Springer Spaniel), the first pet dog to win the PDSA Order of Merit (animal equivalent of OBE)
* Max (gorilla) ...
(via the sprintf object)
*
Mythryl
*
PARI/GP
*
Perl
*
PHP
*
Python (via operator)
*
R
*
Raku (via , , and )
*
Red/System
*
Ruby
*
Tcl (via format command)
*
Transact-SQL (vi
xp_sprintf
*
Vala (via and )
*The
utility command, sometimes built in to the shell, such as with some implementations of the
KornShell
KornShell (ksh) is a Unix shell which was developed by David Korn at Bell Labs in the early 1980s and announced at USENIX on July 14, 1983. The initial development was based on Bourne shell source code. Other early contributors were Bell ...
(ksh),
Bourne again shell (bash), or
Z shell (zsh). These commands usually interpret
C escapes in the format string.
See also
*
Format (Common Lisp)
*
C standard library
The C standard library or libc is the standard library for the C programming language, as specified in the ISO C standard.ISO/IEC (2018). '' ISO/IEC 9899:2018(E): Programming Languages - C §7'' Starting from the original ANSI C standard, it wa ...
*
Format string attack
Uncontrolled format string is a type of software vulnerability discovered around 1989 that can be used in security exploits. Originally thought harmless, format string exploits can be used to crash a program or to execute harmful code. The problem ...
*
iostream
*
ML (programming language)
*
printf debugging
*
(Unix)
*
printk
(print kernel messages)
*
scanf
*
string interpolation
In computer programming, string interpolation (or variable interpolation, variable substitution, or variable expansion) is the process of evaluating a string literal containing one or more placeholders, yielding a result in which the placeholders ...
References
External links
C++ reference for *
*Th
in Java 1.5
GNU Bash builtin
{{Unix commands
Articles with example C code
C standard library
Unix software