1formats(5) Standards, Environments, and Macros formats(5)
2
6 formats - file format notation
7
9 Utility descriptions use a syntax to describe the data organization
10 within files—stdin, stdout, stderr, input files, and output files—when
11 that organization is not otherwise obvious. The syntax is similar to
12 that used by the printf(3C) function. When used for stdin or input
13 file descriptions, this syntax describes the format that could have
14 been used to write the text to be read, not a format that could be used
15 by the scanf(3C) function to read the input file.
16 Format
18 The description of an individual record is as follows:
19 "<format>", [<arg1>, <arg2>, ..., <argn>]
21 The format is a character string that contains three types of objects
25 defined below:
26 characters Characters that are not escape sequences
28 or conversion specifications, as
29 described below, are copied to the out‐
30 put.
31 escape sequences Represent non-graphic characters.
34 conversion specifications Specifies the output format of each argu‐
37 ment. (See below.)
38 The following characters have the following special meaning in the for‐
42 mat string:
43 `` '' (An empty character position.) One or more blank characters.
45 /\ Exactly one space character.
48 The notation for spaces allows some flexibility for application output.
52 Note that an empty character position in format represents one or more
53 blank characters on the output (not white space, which can include new‐
54 line characters). Therefore, another utility that reads that output as
55 its input must be prepared to parse the data using scanf(3C), awk(1),
56 and so forth. The character is used when exactly one space character
57 is output.
58 Escape Sequences
60 The following table lists escape sequences and associated actions on
61 display devices capable of the action.
62 Sequence Character Terminal Action
68 ─────────────────────────────────────────────────────────────────
69 \\ backslash None.
70 \a alert Attempts to alert the user
71 through audible or visible
72 notification.
73 \b backspace Moves the printing position to
74 one column before the current
75 position, unless the current
76 position is the start of a
77 line.
78 \f form-feed Moves the printing position to
79 the initial printing position
80 of the next logical page.
81 \n newline Moves the printing position to
82 the start of the next line.
83 \r carriage-return Moves the printing position to
84 the start of the current line.
85 \t tab Moves the printing position to
86 the next tab position on the
87 current line. If there are no
88 more tab positions left on the
89 line, the behavior is unde‐
90 fined.
91 \v vertical-tab Moves the printing position to
92 the start of the next vertical
93 tab position. If there are no
94 more vertical tab positions
95 left on the page, the behavior
96 is undefined.
97 Conversion Specifications
100 Each conversion specification is introduced by the percent-sign charac‐
101 ter (%). After the character %, the following appear in sequence:
102 flags Zero or more flags, in any order, that modify
104 the meaning of the conversion specification.
105 field width An optional string of decimal digits to spec‐
108 ify a minimum field width. For an output
109 field, if the converted value has fewer bytes
110 than the field width, it is padded on the
111 left (or right, if the left-adjustment flag
112 (−), described below, has been given to the
113 field width).
114 precision Gives the minimum number of digits to appear
117 for the d, o, i, u, x or X conversions (the
118 field is padded with leading zeros), the num‐
119 ber of digits to appear after the radix char‐
120 acter for the e and f conversions, the maxi‐
121 mum number of significant digits for the g
122 conversion; or the maximum number of bytes to
123 be written from a string in s conversion. The
124 precision takes the form of a period (.) fol‐
125 lowed by a decimal digit string; a null digit
126 string is treated as zero.
127 conversion characters A conversion character (see below) that indi‐
130 cates the type of conversion to be applied.
131 flags
134 The flags and their meanings are:
135 − The result of the conversion is left-justified within the
137 field.
138 + The result of a signed conversion always begins with a sign
141 (+ or −).
142 <space> If the first character of a signed conversion is not a
145 sign, a space character is prefixed to the result. This
146 means that if the space character and + flags both appear,
147 the space character flag is ignored.
148 # The value is to be converted to an alternative form. For c,
151 d, i, u, and s conversions, the behaviour is undefined. For
152 o conversion, it increases the precision to force the first
153 digit of the result to be a zero. For x or X conversion, a
154 non-zero result has 0x or 0X prefixed to it, respectively.
155 For e, E, f, g, and G conversions, the result always con‐
156 tains a radix character, even if no digits follow the radix
157 character. For g and G conversions, trailing zeros are not
158 removed from the result as they usually are.
159 0 For d, i, o, u, x, X, e, E, f, g, and G conversions, lead‐
162 ing zeros (following any indication of sign or base) are
163 used to pad to the field width; no space padding is per‐
164 formed. If the 0 and − flags both appear, the 0 flag is
165 ignored. For d, i, o, u, x and X conversions, if a preci‐
166 sion is specified, the 0 flag is ignored. For other conver‐
167 sions, the behaviour is undefined.
168 Conversion Characters
171 Each conversion character results in fetching zero or more arguments.
172 The results are undefined if there are insufficient arguments for the
173 format. If the format is exhausted while arguments remain, the excess
174 arguments are ignored.
175 The conversion characters and their meanings are:
178 d,i,o,u,x,X The integer argument is written as signed decimal (d or
180 i), unsigned octal (o), unsigned decimal (u), or
181 unsigned hexadecimal notation (x and X). The d and i
182 specifiers convert to signed decimal in the style
183 [−]dddd. The x conversion uses the numbers and letters
184 0123456789abcdef and the X conversion uses the numbers
185 and letters 0123456789ABCDEF. The precision component
186 of the argument specifies the minimum number of digits
187 to appear. If the value being converted can be repre‐
188 sented in fewer digits than the specified minimum, it
189 is expanded with leading zeros. The default precision
190 is 1. The result of converting a zero value with a pre‐
191 cision of 0 is no characters. If both the field width
192 and precision are omitted, the implementation may pre‐
193 cede, follow or precede and follow numeric arguments of
194 types d, i and u with blank characters; arguments of
195 type o (octal) may be preceded with leading zeros.
196 The treatment of integers and spaces is different from
198 the printf(3C) function in that they can be surrounded
199 with blank characters. This was done so that, given a
200 format such as:
201 "%d\n",<foo>
203 the implementation could use a printf() call such as:
205 printf("%6d\n", foo);
207 and still conform. This notation is thus somewhat like
209 scanf() in addition to printf().
210 f The floating point number argument is written in deci‐
213 mal notation in the style [−]ddd.ddd, where the number
214 of digits after the radix character (shown here as a
215 decimal point) is equal to the precision specification.
216 The LC_NUMERIC locale category determines the radix
217 character to use in this format. If the precision is
218 omitted from the argument, six digits are written after
219 the radix character; if the precision is explicitly 0,
220 no radix character appears.
221 e,E The floating point number argument is written in the
224 style [−]d.ddde±dd (the symbol ± indicates either a
225 plus or minus sign), where there is one digit before
226 the radix character (shown here as a decimal point) and
227 the number of digits after it is equal to the preci‐
228 sion. The LC_NUMERIC locale category determines the
229 radix character to use in this format. When the preci‐
230 sion is missing, six digits are written after the
231 radix character; if the precision is 0, no radix char‐
232 acter appears. The E conversion character produces a
233 number with E instead of e introducing the exponent.
234 The exponent always contains at least two digits. How‐
235 ever, if the value to be written requires an exponent
236 greater than two digits, additional exponent digits are
237 written as necessary.
238 g,G The floating point number argument is written in style
241 f or e (or in style E in the case of a G conversion
242 character), with the precision specifying the number of
243 significant digits. The style used depends on the value
244 converted: style g is used only if the exponent result‐
245 ing from the conversion is less than −4 or greater than
246 or equal to the precision. Trailing zeros are removed
247 from the result. A radix character appears only if it
248 is followed by a digit.
249 c The integer argument is converted to an unsigned char
252 and the resulting byte is written.
253 s The argument is taken to be a string and bytes from the
256 string are written until the end of the string or the
257 number of bytes indicated by the precision specifica‐
258 tion of the argument is reached. If the precision is
259 omitted from the argument, it is taken to be infinite,
260 so all bytes up to the end of the string are written.
261 % Write a % character; no argument is converted.
264 In no case does a non-existent or insufficient field width cause trun‐
268 cation of a field; if the result of a conversion is wider than the
269 field width, the field is simply expanded to contain the conversion
270 result. The term field width should not be confused with the term pre‐
271 cision used in the description of %s.
272 One difference from the C function printf() is that the l and h conver‐
275 sion characters are not used. There is no differentiation between deci‐
276 mal values for type int, type long, or type short. The specifications
277 %d or %i should be interpreted as an arbitrary length sequence of dig‐
278 its. Also, no distinction is made between single precision and double
279 precision numbers (float or double in C). These are simply referred to
280 as floating point numbers.
281 Many of the output descriptions use the term line, such as:
284 "%s", <input line>
286 Since the definition of line includes the trailing newline character
290 already, there is no need to include a \n in the format; a double new‐
291 line character would otherwise result.
292
294 Example 1 To represent the output of a program that prints a date and
295 time in the form Sunday, July 3, 10:02, where <weekday> and <month> are
296 strings:
297 "%s,/\%s/\%d,/\%d:%.2d\n",<weekday>,<month>,<day>,<hour>,<min>
299 Example 2 To show pi written to 5 decimal places:
302 "pi/\=/\%.5f\n",<value of pi>
304 Example 3 To show an input file format consisting of five colon-sepa‐
307 rated fields:
308 "%s:%s:%s:%s:%s\n",<arg1>,<arg2>,<arg3>,<arg4>,<arg5>
310
313 awk(1), printf(1), printf(3C), scanf(3C)
314SunOS 5.11 28 Mar 1995 formats(5)