1formats(5)            Standards, Environments, and Macros           formats(5)
2
3
4

NAME

6       formats - file format notation
7

DESCRIPTION

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
17   Format
18       The description of an individual record is as follows:
19
20         "<format>", [<arg1>, <arg2>, ..., <argn>]
21
22
23
24       The  format  is a character string that contains three types of objects
25       defined below:
26
27       characters                    Characters that are not escape  sequences
28                                     or    conversion    specifications,    as
29                                     described below, are copied to  the  out‐
30                                     put.
31
32
33       escape sequences              Represent non-graphic characters.
34
35
36       conversion specifications     Specifies the output format of each argu‐
37                                     ment. (See below.)
38
39
40
41       The following characters have the following special meaning in the for‐
42       mat string:
43
44       `` ''      (An empty character position.) One or more blank characters.
45
46
47       /\         Exactly one space character.
48
49
50
51       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
59   Escape Sequences
60       The  following  table lists escape sequences and  associated actions on
61       display devices capable of the action.
62
63
64
65
66
67         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
98
99   Conversion Specifications
100       Each conversion specification is introduced by the percent-sign charac‐
101       ter (%). After the character %, the following appear in sequence:
102
103       flags                     Zero or more flags, in any order, that modify
104                                 the meaning of the conversion specification.
105
106
107       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
115
116       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
128
129       conversion characters     A conversion character (see below) that indi‐
130                                 cates the type of conversion to be applied.
131
132
133   flags
134       The flags and their meanings are:
135
136                  The  result  of the conversion is left-justified within the
137                   field.
138
139
140       +           The result of a signed conversion always begins with a sign
141                   (+ or −).
142
143
144       <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
149
150       #           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
160
161       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
169
170   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
176
177       The conversion characters and their meanings are:
178
179       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
197                       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
202                         "%d\n",<foo>
203
204                       the implementation could use a printf() call such as:
205
206                         printf("%6d\n", foo);
207
208                       and still conform. This notation is thus somewhat  like
209                       scanf() in addition to printf().
210
211
212       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
222
223       e,E             The  floating  point  number argument is written in the
224                       style []d.ddddd (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
239
240       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
250
251       c               The  integer  argument is converted to an unsigned char
252                       and the resulting byte is written.
253
254
255       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
262
263       %               Write a % character; no argument is converted.
264
265
266
267       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
273
274       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
282
283       Many of the output descriptions  use the term line, such as:
284
285         "%s", <input line>
286
287
288
289       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

EXAMPLES

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
298         "%s,/\%s/\%d,/\%d:%.2d\n",<weekday>,<month>,<day>,<hour>,<min>
299
300
301       Example 2 To show pi written to 5 decimal places:
302
303         "pi/\=/\%.5f\n",<value of pi>
304
305
306       Example  3  To show an input file format consisting of five colon-sepa‐
307       rated fields:
308
309         "%s:%s:%s:%s:%s\n",<arg1>,<arg2>,<arg3>,<arg4>,<arg5>
310
311

SEE ALSO

313       awk(1), printf(1), printf(3C), scanf(3C)
314
315
316
317SunOS 5.11                        28 Mar 1995                       formats(5)
Impressum