Standards, Environments, and Macros formats(5)
NAME
formats - file format notation
DESCRIPTION
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 other-
wise 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.
Format
The description of an individual record is as follows:
"", [, , ..., ]
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 out-
put.
escape sequences Represent non-graphic charac-
ters.
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.
SunOS 5.11 Last change: 28 Mar 1995 1
Standards, Environments, and Macros formats(5)
The notation for spaces allows some flexibility for applica-
tion 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). There-
fore, 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.
Escape Sequences
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 unde-
fined.
\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.
Conversion Specifications
Each conversion specification is introduced by the percent-
sign character (%). After the character %, the following
appear in sequence:
SunOS 5.11 Last change: 28 Mar 1995 2
Standards, Environments, and Macros formats(5)
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 conver-
sions, the maximum number of sig-
nificant digits for the g conver-
sion; 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 conver-
sion 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 -).
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
SunOS 5.11 Last change: 28 Mar 1995 3
Standards, Environments, and Macros formats(5)
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 conver-
sion, a non-zero result has 0x or 0X prefixed to
it, respectively. For e, E, f, g, and G conver-
sions, the result always contains a radix char-
acter, even if no digits follow the radix char-
acter. 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 conver-
sions, 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 preci-
sion is specified, the 0 flag is ignored. For
other conversions, the behaviour is undefined.
Conversion Characters
Each conversion character results in fetching zero or more
arguments. The results are undefined if there are insuffi-
cient 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 hexade-
cimal 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 con-
verted 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
SunOS 5.11 Last change: 28 Mar 1995 4
Standards, Environments, and Macros formats(5)
with a precision of 0 is no characters. If
both the field width and precision are omit-
ted, 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 dif-
ferent from the printf(3C) function in that
they can be surrounded with blank charac-
ters. This was done so that, given a format
such as:
"%d\n",
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 writ-
ten 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 specifica-
tion. The LCNUMERIC locale category deter-
mines 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 expli-
citly 0, no radix character appears.
e,E The floating point number argument is writ-
ten 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 LCNUMERIC 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
SunOS 5.11 Last change: 28 Mar 1995 5
Standards, Environments, and Macros formats(5)
of e introducing the exponent. The exponent
always contains at least two digits. How-
ever, 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 writ-
ten in style f or e (or in style E in the
case of a G conversion character), with the
precision specifying the number of signifi-
cant 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 con-
verted.
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 dif-
ferentiation between decimal values for type int, type
long, or type short. The specifications %d or %i should be
SunOS 5.11 Last change: 28 Mar 1995 6
Standards, Environments, and Macros formats(5)
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",
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.
EXAMPLES
Example 1 To represent the output of a program that prints a
date and time in the form Sunday, July 3, 10:02, where
and are strings:
"%s,/\%s/\%d,/\%d:%.2d\n",,,,,
Example 2 To show pi written to 5 decimal places:
"pi/\=/\%.5f\n",
Example 3 To show an input file format consisting of five
colon-separated fields:
"%s:%s:%s:%s:%s\n",,,,,
SEE ALSO
awk(1), printf(1), printf(3C), scanf(3C)
SunOS 5.11 Last change: 28 Mar 1995 7
