Utility descriptions use a syntax to describe the data
organization within files—stdin, stdout, stderr, input files, and
output files—when that organization is not otherwise obvious. The
syntax is similar to that used by the printf(3C) function. When used
for stdin or input file descriptions, this syntax describes the format that
could have been used to write the text to be read, not a format that could
be used by the scanf(3C) function to read the input file.
The description of an individual record is as follows:
"<format>", [<arg1>, <arg2>, ..., <argn>]
The format is a character string that contains three types
of objects defined below:
characters
Characters that are not escape sequences or
conversion specifications, as described below, are copied to the
output.
escape sequences
Represent non-graphic characters.
conversion specifications
Specifies the output format of each argument. (See
below.)
The following characters have the following special meaning in the
format string:
`` ''
(An empty character position.) One or more blank
characters.
/\
Exactly one space character.
The notation for spaces allows some flexibility for application
output. Note that an empty character position in format represents
one or more blank characters on the output (not white space, which
can include newline characters). Therefore, another utility that reads that
output as its input must be prepared to parse the data using
scanf(3C), awk(1), and so forth. The character is used when
exactly one space character is output.
The following table lists escape sequences and associated actions
on display devices capable of the action.
| Sequence |
Character |
Terminal Action |
| \\ |
backslash |
None. |
| \a |
alert |
Attempts to alert the user through audible or visible notification. |
| \b |
backspace |
Moves the printing position to one column before the current position,
unless the current position is the start of a line. |
| \f |
form-feed |
Moves the printing position to the initial printing position of the next
logical page. |
| \n |
newline |
Moves the printing position to the start of the next line. |
| \r |
carriage-return |
Moves the printing position to the start of the current line. |
| \t |
tab |
Moves the printing position to the next tab position on the current
line. If there are no more tab positions left on the line, the behavior is
undefined. |
| \v |
vertical-tab |
Moves the printing position to the start of the next vertical tab
position. If there are no more vertical tab positions left on the page,
the behavior is undefined. |
Each conversion specification is introduced by the percent-sign
character (%). After the character %, the following appear in sequence:
flags
Zero or more flags, in any order, that modify the
meaning of the conversion specification.
field width
An optional string of decimal digits to specify a minimum
field width. For an output field, if the converted value has fewer
bytes than the field width, it is padded on the left (or right, if the
left-adjustment flag (−), described below, has been given to the field
width).
precision
Gives the minimum number of digits to appear for the d,
o, i, u, x or X conversions (the field is padded with leading zeros), the
number of digits to appear after the radix character for the e and f
conversions, the maximum number of significant digits for the g conversion; or
the maximum number of bytes to be written from a string in s conversion. The
precision takes the form of a period (.) followed by a decimal digit string; a
null digit string is treated as zero.
conversion characters
A conversion character (see below) that indicates the
type of conversion to be applied.
flags
The flags and their meanings are:
−
The result of the conversion is left-justified within the
field.
+
The result of a signed conversion always begins with a
sign (+ or −).
<space>
If the first character of a signed conversion is not a
sign, a space character is prefixed to the result. This means that if the
space character and + flags both appear, the space character flag is
ignored.
#
The value is to be converted to an alternative form. For
c, d, i, u, and s conversions, the behaviour is undefined. For o conversion,
it increases the precision to force the first digit of the result to be a
zero. For x or X conversion, a non-zero result has 0x or 0X prefixed to it,
respectively. For e, E, f, g, and G conversions, the result always contains a
radix character, even if no digits follow the radix character. For g and G
conversions, trailing zeros are not removed from the result as they usually
are.
0
For d, i, o, u, x, X, e, E, f, g, and G conversions,
leading zeros (following any indication of sign or base) are used to pad to
the field width; no space padding is performed. If the 0 and − flags
both appear, the 0 flag is ignored. For d, i, o, u, x and X conversions, if a
precision is specified, the 0 flag is ignored. For other conversions, the
behaviour is undefined.
Each conversion character results in fetching zero or more
arguments. The results are undefined if there are insufficient arguments for
the format. If the format is exhausted while arguments remain, the excess
arguments are ignored.
The conversion characters and their meanings are:
d,i,o,u,x,X
The integer argument is written as signed decimal (d or
i), unsigned octal (o), unsigned decimal (u), or unsigned hexadecimal notation
(x and X). The d and i specifiers convert to signed decimal in the style
[−
]dddd. The x conversion uses the numbers and
letters 0123456789abcdef and the X conversion uses the numbers and letters
0123456789ABCDEF. The
precision component of the argument specifies the
minimum number of digits to appear. If the value being converted can be
represented in fewer digits than the specified minimum, it is expanded with
leading zeros. The default precision is 1. The result of converting a zero
value with a precision of 0 is no characters. If both the field width and
precision are omitted, the implementation may precede, follow or precede and
follow numeric arguments of types d, i and u with blank characters; arguments
of type o (octal) may be preceded with leading zeros.
The treatment of integers and spaces is different from the
printf(3C) function in that they can be surrounded with blank
characters. This was done so that, given a format such as:
"%d\n",<foo>
the implementation could use a printf() call such as:
printf("%6d\n", foo);
and still conform. This notation is thus somewhat like
scanf() in addition to printf().
f
The floating point number argument is written in decimal
notation in the style [−]ddd.ddd, where the
number of digits after the radix character (shown here as a decimal point) is
equal to the precision specification. The LC_NUMERIC locale
category determines the radix character to use in this format. If the
precision is omitted from the argument, six digits are written after
the radix character; if the precision is explicitly 0, no radix
character appears.
e,E
The floating point number argument is written in the
style [−]d.ddde±dd (the
symbol ± indicates either a plus or minus sign), where there is one
digit before the radix character (shown here as a decimal point) and the
number of digits after it is equal to the precision. The LC_NUMERIC
locale category determines the radix character to use in this format. When the
precision is missing, six digits are written after the radix character; if the
precision is 0, no radix character appears. The E conversion character
produces a number with E instead of e introducing the exponent. The exponent
always contains at least two digits. However, if the value to be written
requires an exponent greater than two digits, additional exponent digits are
written as necessary.
g,G
The floating point number argument is written in style f
or e (or in style E in the case of a G conversion character), with the
precision specifying the number of significant digits. The style used depends
on the value converted: style g is used only if the exponent resulting from
the conversion is less than −4 or greater than or equal to the
precision. Trailing zeros are removed from the result. A radix character
appears only if it is followed by a digit.
c
The integer argument is converted to an unsigned
char and the resulting byte is written.
s
The argument is taken to be a string and bytes from the
string are written until the end of the string or the number of bytes
indicated by the precision specification of the argument is reached. If
the precision is omitted from the argument, it is taken to be infinite, so all
bytes up to the end of the string are written.
%
Write a % character; no argument is converted.
In no case does a non-existent or insufficient field width
cause truncation of a field; if the result of a conversion is wider than the
field width, the field is simply expanded to contain the conversion result.
The term field width should not be confused with the term
precision used in the description of %s.
One difference from the C function printf() is that the l
and h conversion characters are not used. There is no differentiation
between decimal values for type int, type long, or type
short. The specifications %d or %i should be interpreted as an
arbitrary length sequence of digits. Also, no distinction is made between
single precision and double precision numbers (float or double
in C). These are simply referred to as floating point numbers.
Many of the output descriptions use the term line, such
as:
"%s", <input line>
Since the definition of line includes the trailing newline
character already, there is no need to include a \n in the format; a
double newline character would otherwise result.
Example 1 To represent the output of a program that prints
a date and time in the form Sunday, July 3, 10:02, where
<weekday> and <month> are strings:
"%s,/\%s/\%d,/\%d:%.2d\n",<weekday>,<month>,<day>,<hour>,<min>
Example 2 To show pi written to 5 decimal places:
"pi/\=/\%.5f\n",<value of pi>
Example 3 To show an input file format consisting of five
colon-separated fields:
"%s:%s:%s:%s:%s\n",<arg1>,<arg2>,<arg3>,<arg4>,<arg5>