You are viewing the version of this documentation from Perl 5.6.0. View the latest version
sprintf FORMAT, LIST

Returns a string formatted by the usual printf conventions of the C library function sprintf. See sprintf(3) or printf(3) on your system for an explanation of the general principles.

Perl does its own sprintf formatting--it emulates the C function sprintf, but it doesn't use it (except for floating-point numbers, and even then only the standard modifiers are allowed). As a result, any non-standard extensions in your local sprintf are not available from Perl.

Perl's sprintf permits the following universally-known conversions:

%%   a percent sign
%c   a character with the given number
%s   a string
%d   a signed integer, in decimal
%u   an unsigned integer, in decimal
%o   an unsigned integer, in octal
%x   an unsigned integer, in hexadecimal
%e   a floating-point number, in scientific notation
%f   a floating-point number, in fixed decimal notation
%g   a floating-point number, in %e or %f notation

In addition, Perl permits the following widely-supported conversions:

%X   like %x, but using upper-case letters
%E   like %e, but using an upper-case "E"
%G   like %g, but with an upper-case "E" (if applicable)
%b   an unsigned integer, in binary
%p   a pointer (outputs the Perl value's address in hexadecimal)
%n   special: *stores* the number of characters output so far
     into the next variable in the parameter list 

Finally, for backward (and we do mean "backward") compatibility, Perl permits these unnecessary but widely-supported conversions:

%i   a synonym for %d
%D   a synonym for %ld
%U   a synonym for %lu
%O   a synonym for %lo
%F   a synonym for %f

Perl permits the following universally-known flags between the % and the conversion letter:

space   prefix positive number with a space
+       prefix positive number with a plus sign
-       left-justify within the field
0       use zeros, not spaces, to right-justify
#       prefix non-zero octal with "0", non-zero hex with "0x"
number  minimum field width
.number "precision": digits after decimal point for
        floating-point, max length for string, minimum length
        for integer
l       interpret integer as C type "long" or "unsigned long"
h       interpret integer as C type "short" or "unsigned short"
        If no flags, interpret integer as C type "int" or "unsigned"

There are also two Perl-specific flags:

V       interpret integer as Perl's standard integer type
v       interpret string as a vector of integers, output as
        numbers separated either by dots, or by an arbitrary
        string received from the argument list when the flag
        is preceded by C<*>

Where a number would appear in the flags, an asterisk (*) may be used instead, in which case Perl uses the next item in the parameter list as the given number (that is, as the field width or precision). If a field width obtained through * is negative, it has the same effect as the - flag: left-justification.

The v flag is useful for displaying ordinal values of characters in arbitrary strings:

printf "version is v%vd\n", $^V;            # Perl's version
printf "address is %*vX\n", ":", $addr;     # IPv6 address
printf "bits are %*vb\n", " ", $bits;       # random bitstring

If use locale is in effect, the character used for the decimal point in formatted real numbers is affected by the LC_NUMERIC locale. See perllocale.

If Perl understands "quads" (64-bit integers) (this requires either that the platform natively support quads or that Perl be specifically compiled to support quads), the characters

d u o x X b i D U O

print quads, and they may optionally be preceded by

ll L q

For example

%lld %16LX %qo

You can find out whether your Perl supports quads via Config:

use Config;
($Config{use64bitint} eq 'define' || $Config{longsize} == 8) &&
        print "quads\n";

If Perl understands "long doubles" (this requires that the platform support long doubles), the flags

e f g E F G

may optionally be preceded by

ll L

For example

%llf %Lg

You can find out whether your Perl supports long doubles via Config:

use Config;
$Config{d_longdbl} eq 'define' && print "long doubles\n";