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";