printf(1)

Synopsis

Description

format

a character string that contains three types of items:

literal characters

which are copied to the output stream

conversion specifications

each of which results in fetching zero or more args

escape sequences

which are translated into the other characters. Escape sequences represent the following nongraphic characters:

\a	alert	\n	newline
\b	backspace	\t	tab
\r	carriage return	\v	vertical tab
\f	form feed	\\	backslash

 \a   alert             \n   newline
 \b   backspace         \t   tab
 \r   carriage return   \v   vertical tab
 \f   form feed         \\   backslash

and \ddd where ddd is a one, two, or three digit octal number. One byte with the numeric value specified by the octal number is output.

arg

string(s) to be printed under the control of format. The results are equivalent to null strings or zero values if there are insufficient args for the format. If the format is exhausted while args remain, the format is re-used, treating the first remaining arg as if it were the first arg. However, if any position fields are present in any conversion specifications, any remaining args are ignored, see below.

Each conversion specification is introduced by the character ``%''. After the ``%'', the following appear in sequence:

position

An optional field, consisting of a positive decimal integer followed by a ``$'', specifying the next arg to be converted. If this field is not provided, the arg following the last arg converted is used. If this field is present in any conversion specifications in the format, any args remaining after the format is exhausted are simply ignored.

flags

Zero or more flags, in any order, that modify the meaning of the conversion specification. The following flags are supported:

-

The result of the conversion is left-justified in the field.

+

The result of a signed conversion always begins with a sign (which can be + or -).

space

If the first character of a signed conversion is not a sign, a space is placed before the result. If the space and + flags both appear, the space flag is ignored.

#

For o conversion, the precision is increased (if needed) to force the first digit of the result to be zero. For x and X conversions, 0x or 0X is placed before the result if it is nonzero.

0

For d, i, o, u, x, and X conversions, the field width is padded with leading zeros (following an indication of sign or base); no space padding is performed. If the 0 and - flags both appear or if a precision is specified, the 0 flag is ignored.

field width

An optional string of decimal digits that specify a minimum field width. Without the left-adjust flag (-), the converted value in the output field is padded on the left. With the - flag, it is padded on the right.

precision

For the d, o, i, u, x, or X conversions, precision gives the minimum number of digits to appear; the field is padded with leading zeros. For an s conversion, precision gives the maximum number of bytes to be written from a string. precision takes the form of a period (``.'') followed by a string of decimal digits; a null string is treated as zero.

conversion characters

A conversion character from those listed below that indicates the type of conversion to be applied.

d, i, o, u, x, X

For each of these characters, the precision component gives the minimum number of digits to appear. With the exception of o conversions, if the value being converted can fit into fewer digits that the given minimum, it is expanded with leading zeros. The default precision is 1. Converting a zero value with a precision of zero results in no characters. The argument operand is treated as a C constant with the following extensions:

• a leading plus or minus sign is allowed, and

• if the leading character is a single or double quote, the value is the numeric value of the character following the quote in the underlying code set.

The effects of each of these conversion characters is as follows:

d, i

Written as a signed decimal which is converted in the style [-]dddd.

o

Written as unsigned octal.

u

Written as unsigned decimal.

x

Hexadecimal using 0123456789abcedf as digits.

X

Hexadecimal using 0123456789ABCEDF as digits.

c

The integer argument is treated as a string and is converted to unsigned character and the resulting byte is written.

b

The argument is a string that may contain backslash-escape sequences. All the supported escape sequences listed under escape sequences above and \0ddd and \c are supported. The \0ddd sequence is the same as the normal \ddd sequence. \c is not written and causes printf to ignore any remaining characters in the string operand containing \c, any remaining string operands, and any additional characters in the format operand.

Bytes from the converted string are written until the end of the string or the number of bytes indicated by precision is reached. If precision is omitted, all bytes up to the end of the string are written.

%

Write the ``%'' character; no argument is written.

For each specification that consumes an argument, the next argument operand is evaluated and converted to the appropriate type for the conversion.

The format operand is reused as often as necessary to satisfy of the argument operands. An extra ``c'' or ``s'' conversion specification is evaluated as if a null string argument was given. If other conversion specifications are extra, they are evaluated as if a zero argument was given.

If an argument operand cannot be completely converted into an internal value that is appropriate to the corresponding conversion specification, a diagnostic message is written to standard error and the final exit status will be non-zero. It continues to process remaining operands and writes to standard output the value accumulated at the time the error was detected.

Examples

results in the output:

   Good Morning World

The following command produces the same output.

printf '%2$s %s %1$s\n' World Good Morning

Here is an example that prints the first 6 characters of $PATH left-adjusted in a 10-character field:

printf 'First 6 chars of %s are %-10.6s.\n' $PATH $PATH

If $PATH has the value /usr/bin:/usr/local/bin, then the above command would print the following output:

   First 6 chars of /usr/bin:/usr/local/bin are /usr/b    .

The command:

printf "%5d%4d\n" 1 21 321 4321 54321

produces:

       1  21
     3214321
   54321   0

The format operand is used three times to print all of the given strings. The ``0'' in the last line of the output is supplied by printf to satisfy the last %4d conversion specification.

References