printf

printfis aCstandard libraryfunctionthatformatstextand writes it tostandard output.

An example of the printf function

The name,printfis short forprint formattedwhereprintrefers to output to aprinteralthough the functions are not limited to printer output.

The standard library provides many other similar functions that form a family ofprintf-likefunctions. These functions accept aformat stringparameter and avariablenumber of value parameters that the functionserializesper the format string and writes to anoutput streamor astring buffer.

The format string isencodedas atemplate languageconsisting of verbatim text andformat specifiersthat each specify how to serialize a value. As the format string is processedleft-to-right,a subsequent value is used for each format specifier found. A format specifier starts with a%character and has one or more following characters that specify how to serialize a value.

The format stringsyntaxandsemanticsis the same for all of the functions in the printf-like family.

Mismatch between the format specifiers and count andtypeof values can cause acrashorvulnerability.

The printf format string is complementary to thescanf format string,which provides formatted input (lexinga.k.a.parsing). Both format strings provide relatively simple functionality compared to other template engines, lexers and parsers.

The formatting design has been copied in otherprogramming languages.

History

1950s: Fortran

Early programming languages likeFortranused special statements with different syntax from other calculations to build formatting descriptions.In this example, the format is specified on line601,and thePRINTcommand refers to it by line number:

PRINT601,IA,IB,AREA
601FORMAT(4HA=,I5,5HB=,I5,8HAREA=,F10.2,13HSQUAREUNITS)

Hereby:

• 4Hindicates astringof 4characters"A="(HmeansHollerith Field);
• I5indicates anintegerfield of width 5;
• F10.2indicates afloating-pointfield of width 10 with 2 digits after the decimal point.

An output with input arguments100,200,and1500.25might look like this:

A= 100 B= 200 AREA= 1500.25 SQUARE UNITS

1960s: BCPL and ALGOL 68

In 1967,BCPLappeared.Its library included thewritefroutine.An example application looks like this:

WRITEF( "%I2-QUEENS PROBLEM HAS %I5 SOLUTIONS*N", NUMQUEENS, COUNT)

Hereby:

• %I2indicates anintegerof width 2 (the order of the format specification's field width and type is reversed compared to C'sprintf);
• %I5indicates an integer of width 5;
• *Nis a BCPLlanguageescape sequencerepresenting anewlinecharacter (for which C uses the escape sequence\n).

In 1968,ALGOL 68had a more function-likeAPI,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,BIN255,3.14,250));

In contrast to Fortran, using normal function calls anddata typessimplifies the language and compiler, and allows the implementation of the input/output to be written in the same language.

These advantages were thought to outweigh the disadvantages (such as a complete lack oftype safetyin many instances) up until the 2000s, and in most newer languages of that era I/O is not part of the syntax.

People have since learnedthat this potentially results in consequences, ranging from security exploits to hardware failures (e.g., phone's networking capabilities being permanently disabled after trying to connect to an access point named "%p%s%s%s%s%n"). Modern languages, such asC++20and later, tend to include format specifications as a part of the language syntax,which restore type safety in formatting to an extent, and allow the compiler to detect some invalid combinations of format specifiers and data types at compile time.

1970s: C

In 1973,printfwas included as aC standard libraryroutine as part ofVersion 4 Unix.

1990s: Shell command

In 1990, aprintfshell commandwas attested as part of4.3BSD-Reno.It is modeled after the C standard library function.

In 1991, aprintfcommand was included with GNU shellutils (now part ofGNU Core Utilities).

2000s: -Wformat safety

The need to do something about the range of problems resulting from lack oftype safetyhas prompted attempts to make the C++ compilerprintf-aware.

The-Wformatoption ofGCCallows compile-time checks toprintfcalls, enabling the compiler to detect a subset of invalid calls (and issue either a warning or an error, stopping the compilation altogether, depending on other flags).

Since the compiler is inspectingprintfformat specifiers, enabling this effectively extends the C++ syntax by making formatting a part of it.

2020s: C++20 Format Specifiers and C++23 print

As said above, numerous issueswithprintf()'s lack oftype safetyresulted in the revisionof approach to formatting, andC++20onwards include format specifications in the languageto enable type-safe formatting.

The approach (and syntax) of C++20std::formatresulted from effectively incorporating Victor Zverovich'slibfmtAPI into the language specification(Zverovich wrotethe first draft of the new format proposal); consequently,libfmtis an implementation of the C++20 format specification.

The formatting function has been combined with output inC++23,which providesthestd::printcommand as a replacement forprintf().

As the format specification has become a part of the language syntax, a C++ compiler is able to prevent invalid combinations of types and format specifiers in many cases. Unlike the-Wformatoption, this is not an optional feature.

The format specification oflibfmtandstd::formatis, in itself, an extensible "mini-language" (referred to as such in the specification),an example of adomain-specific language.

Incorporation of a separate, domain specific mini-language specifically for formatting into the C++ language syntax forstd::print,therefore, completes the historical cycle, bringing the state-of-the-art (as of 2024) back to what it was in the case ofFORTRAN's firstPRINTimplementation in the 1950s discussed in the beginning of this section.

Format specifier

Formatting of a value is specified as markup in the format string. For example, the following outputsYour age isand then the value of the variableagein decimal format.

printf("Your age is %d",age);

Syntax

The syntax for a format specifier is: %[''parameter''][''flags''][''width''][.''precision''][''length'']''type''

Parameter field

The parameter field is optional. If included, then matching specifiers to values isnotsequential. The numeric valuenselects the n-th value parameter.

Character	Description
n$	nis the index of the value parameter toserializeusing this format specifier

This is aPOSIXextension; notC99.

This field allows for using the same value multiple times in a format string instead of having to pass the value multiple times. If a specifier includes this field, then subsequent specifiers must also.

For example,

printf("%2$d %2$#x; %1$d %1$#x",16,17);

outputs:17 0x11; 16 0x10.

This field is particularly useful forlocalizingmessages to differentnatural languagesthat use differentword orders.

InMicrosoft Windows,support for this feature is via a different function,printf_p.

Flags field

The flags field can be zero or more of (in any order):

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 does not 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 does not prepend anything in front of positive numbers.)
0 (zero)	When the 'width' option is specified, prepends zeros for numeric types. (The default prepends spaces.) For example,printf("%4X",3);produces3,whileprintf("%04X",3);produces0003.
' (apostrophe)	The integer or exponent of a decimal has the thousands grouping separator applied.
# (hash)	Alternate form: ForgandGtypes, trailing zeros are not removed. Forf,F,e,E,g,Gtypes, the output always contains a decimal point. Foro,x,Xtypes, the text0,0x,0X,respectively, is prepended to non-zero numbers.

Width field

The width field specifies theminimumnumber of characters to output. If the value can be represented in fewer characters, then the value is left-padded with spaces so that output is the number of characters specified. If the value requires more characters, then the output is longer than the specified width. A value is never truncated.

For example,printf("%3d",12);specifies a width of 3 and outputs12with a space on the left to output 3 characters. The callprintf("%3d",1234);outputs1234which is 4 characters long since that is the minimum width for that value even though the width specified is 3.

If the width field is omitted, the output is the minimum number of characters for the value.

If the field is specified as*,then the width value is read from the list of values in the call.For example,printf("%*d",3,10);outputs10where the second parameter,3,is the width (matches with*) and10is the value toserialize(matches withd).

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 width field can be used to format values as a table (tabulated output). But, columns do not align if any value is larger than fits in the width specified. For example, notice that the last line value (1234) does not fit in the first column of width 3 and therefore the column is not aligned.

1 1
12 12
123 123
1234 123

Precision field

The precision field usually specifies amaximumlimit of the output, depending on the particular formatting type. Forfloating-pointnumeric types, it specifies the number of digits to the right of the decimal point to which the output should be rounded; for%gand%Git specifies the total number ofsignificant digits(before and after the decimal, not including leading or trailing zeroes) to round to. For thestring 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");outputsabc.

Length field

The length field can be omitted or be any of:

Character	Description
hh	For integer types, causesprintfto expect anint-sized integer argument which was promoted from achar.
h	For integer types, causesprintfto expect anint-sized integer argument which was promoted from ashort.
l	For integer types, causesprintfto expect along-sized integer argument. For floating-point types, this is ignored.floatarguments are always promoted todoublewhen used in avarargscall.
ll	For integer types, causesprintfto expect along long-sized integer argument.
L	For floating-point types, causesprintfto expect along doubleargument.
z	For integer types, causesprintfto expect asize_t-sized integer argument.
j	For integer types, causesprintfto expect aintmax_t-sized integer argument.
t	For integer types, causesprintfto expect aptrdiff_t-sized integer argument.

Platform-specific length options came to exist prior to widespread use of the ISO C99 extensions, including:

Characters	Description	Commonly found platforms
I	For signed integer types, causesprintfto expectptrdiff_t-sized integer argument; for unsigned integer types, causesprintfto expectsize_t-sized integer argument.	Win32/Win64
I32	For integer types, causesprintfto expect a 32-bit (double word) integer argument.	Win32/Win64
I64	For integer types, causesprintfto expect a 64-bit (quad word) integer argument.	Win32/Win64
q	For integer types, causesprintfto expect a 64-bit (quad word) integer argument.	BSD

ISO C99 includes theinttypes.hheader file that includes a number ofmacrosfor platform-independentprintfcoding. For example:printf("%"PRId64,t);specifies decimal format for a64-bit signed integer.Since the macros evaluate to astring literal,and the compilerconcatenatesadjacent string literals, the expression"%"PRId64compiles to a single string.

Macros include:

Macro	Description
PRId32	Typically equivalent toI32d(Win32/Win64) ord
PRId64	Typically equivalent toI64d(Win32/Win64),lld(32-bit platforms) orld(64-bit platforms)
PRIi32	Typically equivalent toI32i(Win32/Win64) ori
PRIi64	Typically equivalent toI64i(Win32/Win64),lli(32-bit platforms) orli(64-bit platforms)
PRIu32	Typically equivalent toI32u(Win32/Win64) oru
PRIu64	Typically equivalent toI64u(Win32/Win64),llu(32-bit platforms) orlu(64-bit platforms)
PRIx32	Typically equivalent toI32x(Win32/Win64) orx
PRIx64	Typically equivalent toI64x(Win32/Win64),llx(32-bit platforms) orlx(64-bit platforms)

Type field

The type field can be any of:

Character	Description
%	Prints a literal%character (this type does not accept any flags, width, precision, length fields).
d,i	intas a signedinteger.%dand%iare synonymous for output, but are different when used withscanffor input (where using%iwill interpret a number as hexadecimal if it's preceded by0x,and octal if it's preceded by0.)
u	Print decimalunsigned int.
f,F	doublein normal (fixed-point) notation.fandFonly differs in how the strings for an infinite number orNaNare printed (inf,infinityandnanforf;INF,INFINITYandNANforF).
e,E	doublevalue in standard form (d.ddde±dd). AnEconversion uses the letterE(rather thane) to introduce the exponent. The exponent always contains at least two digits; if the value is zero, the exponent is00.In Windows, the exponent contains three digits by default, e.g.1.5e002,but this can be altered by Microsoft-specific_set_output_formatfunction.
g,G	doublein either normal or exponential notation, whichever is more appropriate for its magnitude.guses lower-case letters,Guses 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, and that the precision field specifies the total number of significant digits rather than the digits after the decimal. Also, the decimal point is not included on whole numbers.
x,X	unsigned intas ahexadecimalnumber.xuses lower-case letters andXuses upper-case.
o	unsigned intinoctal.
s	null-terminated string.
c	char(character).
p	void*(pointer to void) in an implementation-defined format.
a,A	doublein hexadecimal notation, starting with0xor0X.auses lower-case letters,Auses upper-case letters.(C++11'sstd::iostreamclass provides ahexfloatthat works the same).
n	Print nothing, but writes the number of characters written so far into an integerpointerparameter. InJavathis prints anewline.

Custom data type formatting

A common way to handle formatting with a custom data type is to format the custom data type value into astring,then use the%sspecifier to include theserializedvalue in a larger message.

Some printf-like functions allow extensions to theescape-character-basedmini-language,thus allowing the programmer to use a specific formatting function for non-builtin types. One is the (nowdeprecated)glibc'sregister_printf_function().However, it is rarely used due to the fact that it conflicts withstatic format string checking.Another isVstr custom formatters,which allows adding multi-character format names.

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

TheLinux kernelprintkfunction supports a number of ways to display kernel structures using the generic%pspecification, byappendingadditional format characters.For example,%pI4prints anIPv4 addressin dotted-decimal form. This allows static format string checking (of the%pportion) at the expense of full compatibility with normal printf.

Family

Variants ofprintfprovide the formatting features but with additional or slightly different behavior.

fprintfoutputs to a systemfile objectinstead ofstandard output.

sprintfwrites to astring bufferinstead of standard output.

snprintfprovides a level of safety oversprintfsince the caller provides a length (n) parameter that specifies the maximum number or chars to write to the buffer.

For most printf-family functions, there is a variant that acceptsva_listrather than a variable length parameter list. For example, there is avfprintf,vsprintf,vsnprintf.

Vulnerabilities

Format string attack

Main article:format string attack

Extra value parameters are ignored, but if the format string has more format specifiers than value parameters passed thebehavior is undefined.For some C compilers, an extra format specifier results in consuming a value even though there isn't one. This can allow theformat string attack.Generally, for C, arguments arepassed on the stack.If too few arguments are passed, then printf can read past the end of the stack frame, thus allowing an attacker to read the stack.

Some compilers, likethe GNU Compiler Collection,willstatically checkthe format strings of printf-like functions and warn about problems (when using the flags-Wallor-Wformat). GCC will also warn about user-defined printf-style functions if the non-standard "format"__attribute__is applied to the function.

Uncontrolled format string exploit

The format string is often astring literal,which allowsstatic analysisof the function call. However, the format string can be the value of avariable,which allows for dynamic formatting but also a security vulnerability known as anuncontrolled format stringexploit.

Memory write

Although an output function on the surface,printfallows writing to a memory location specified by an argument via%n.This functionality is occasionally used as a part of more elaborate format-string attacks.

The%nfunctionality also makesprintfaccidentallyTuring-completeeven with a well-formed set of arguments. A game of tic-tac-toe written in the format string is a winner of the 27thIOCCC.

Programming languages with printf

Notable programming languages that include printf or printf-like functionality:

Excluded are languages that use format strings that deviate from the style in this article (such asAMPLandElixir), languages that inherit their implementation from theJVMor other environment (such asClojureandScala), and languages that do not have a standard native printf implementation but have external libraries which emulate printf behavior (such asJavaScript).

• awk
• C
• C++
• D
• F#
• G (LabVIEW)
• GNU MathProg
• GNU Octave
• Go
• Haskell
• J
• Java(since version 1.5) and JVM languages
• Julia(via Printf standard library)
• Lua(string.format)
• Maple
• MATLAB
• Max(via thesprintfobject)
• Mythryl
• Objective-C
• OCaml(via the Printf module)
• PARI/GP
• Perl
• PHP
• Python(via%operator)
• R
• Raku(viaprintf,sprintf,andfmt)
• Red/System
• Ruby
• Tcl(viaformatcommand)
• Transact-SQL(viaxp_sprintf)
• Vala(viaprint()andFileStream.printf())

See also

• "Hello, World!" program– A basic example program first featured inThe C Programming Language(the "K&R Book" ), which in the C example uses printf to output the message "Hello, World!"
• Format (Common Lisp)– function in Common Lisp that can produce formatted text using a format string similar to the printf format stringPages displaying wikidata descriptions as a fallback
• C standard library– Standard library for the C programming language
• Format string attack– Type of software vulnerabilityPages displaying short descriptions of redirect targets
• std::iostream– C++ standard library header for input/outputPages displaying short descriptions of redirect targets
• ML (programming language)– General purpose functional programming language
• printf debugging– Fixing defects in an engineered systemPages displaying short descriptions of redirect targets
• printf(Unix)– Standard UNIX utility
• printk– Linux kernel C function
• scanf– Control parameter used in programming languages
• string interpolation– Replacing placeholders in a string with values

External links

• C++ reference forstd::fprintf
• gcc printf format specifications quick reference
• printf:print formatted output – System Interfaces Reference,The Single UNIX Specification,Version 4 fromThe Open Group
• TheFormatterspecificationinJava 1.5
• GNU Bashprintf(1)builtin