printf

Write formatted output (POSIX)

Syntax:

printf format [argument...]

Runs on:

Neutrino

Options:

format

A string describing how the given arguments are to be formatted.

argument

A string to be written to standard output, under control of format.

Description:

The printf utility writes formatted arguments to standard output under control of the format control string (the syntax for format is based upon the printf() function).

The format control string contains the following types of characters:

• Ordinary characters that are written exactly as they occur in the format string
• Escape sequences that represent nongraphic characters
• Conversion specifications that specify the output format of the named arguments.

Introduce a conversion specification by the % character. To literally display this character, encode it as %%. Immediately following the % character, you may specify any of the following, in order:

<flags><width><precision><type len><conversion>

where:

flags

Format control flags.

width

Field width.

precision

Numerical precision.

type len

Type length modifier.

conversion

Conversion character.

These components are processed from left to right.

Format control flags

The format control flags modify the meaning of the conversion specification. You can specify zero or more of these flags, in any order:

-

Left justify output within the field.

+

Always begin the result of a signed conversion with a sign (+ or -).

Space

If the first character of a conversion isn't a sign, prefix a space to the result.

#

Convert the value to an alternate form:

For this conversion:	The result is formatted as follows:
o (octal)	The first digit is zero
X or x (hex)	A nonzero result has 0X or 0x prefixed to it
e, E, f, g, and G	The result always has a decimal point (.), even if no digits follow
g and G	Trailing zeros aren't removed from the result as they usually are
c, d, i, s, and u	No effect; the # is ignored
0	For all conversions, pad the field width with leading zeros. The 0 flag is ignored for the d, i, o, u, X, and x conversions if a precision is specified; it's also ignored if the - flag is given.

Field width

An optional decimal integer that specifies the minimum number of characters for displaying the formatted item. If no field width is specified, or if the value is less than the number of characters required to represent the converted value (subject to the specified precision), a field of sufficient width to contain the converted value is used.

If the number of characters required to represent the converted value is less than the field width, the value is padded on the left (or on the right if the - format control flag is given) with spaces or “0” (zero) characters. If the field width begins with a zero, the value is padded with zeros, otherwise spaces.

Precision

An optional decimal integer following a period character (.). The effect of the given precision depends on the conversion character you specify (see “Conversion character,” below).

Type length

An optional character that modifies the interpreted size of the conversion character. The only supported type length character is l (“el”), which causes a d, i, o, u, X, or x conversion to process a long int or unsigned long int argument.

Conversion character

A character that determines the type of conversion to be applied. For example, if d is specified, printf treats the corresponding argument as a decimal integer. The conversion characters are:

d i o u X x

The argument is an integral value. It's printed as one of the following:

• signed decimal (d or i)
• unsigned octal (o)
• unsigned decimal (u)
• unsigned hexadecimal (X or x)

For each of these, the specified precision is interpreted as the minimum number of digits to appear (defaults to 1 if no precision is specified). In the absence of a type length specifier, these conversions are either signed in the range -32768 to 32767 or unsigned in the range 0 to 65535. If a type length is specified, the conversions are either signed in the range -2147483648 to 2147483647 or unsigned in the range 0 to 4294967295. For the hex format, the case of the specifier (X or x) implies the case of the output.

e, E

The argument is a floating-point value, and is displayed in scientific notation. The value is printed in the style:

[-]d[.ddd]e{+|-}dd
     

The first part is an optional sign. The second is a single digit, which is nonzero if the argument is nonzero. The third (optional) part — a decimal character followed by a number of digits equal to the specified precision — is printed if the precision is nonzero. If the precision isn't specified, it's assumed to be 6. If the precision is 0, the decimal isn't printed. The fourth part is an e or E, based upon the case of the conversion character, followed by a signed value. This value represents the order of magnitude.

f

The argument is a floating-point value. The value is printed in the style:

[-]ddd.ddd
    

where the number of digits printed after the decimal character is equal to the specified precision. If the precision isn't specified, it's assumed to be 6. If the precision is 0, the decimal isn't printed.

g, G

The argument is a floating-point value. The value is printed in the “e” style (or “E” style if a G conversion character is given) if the exponent in this style is less than -4 or greater than or equal to the specified precision; otherwise, the value is printed in the “f” style.

c

The first character of the argument is printed.

s

The argument is a string of characters and the string is printed. The number of characters printed from the string is equal to the precision, if specified. The string is left- or right-justified within the specified field width. If no field width is specified, no padding is applied.

Escape sequences

The printf utility interprets the character escape sequences within the format string in a way similar to the C programming language. These sequences, which you introduce via the backslash character (\), are translated as follows:

Examples:

Display the string “hello, world” on a line by itself:

printf "hello, world\n"

Do the same as above, but don't output a newline:

printf "hello, world"

Display a value in scientific notation:

printf "n = %e\n" 3.1415926535897

Exit status:

0

Successful completion.

>0

An error occurred.

See also:

echo, ksh's print command