FORMATS(7) Standards, Environments, and Macros FORMATS(7) NNAAMMEE formats - file format notation DDEESSCCRRIIPPTTIIOONN 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 pprriinnttff(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 ssccaannff(3C) function to read the input file. FFoorrmmaatt The description of an individual record is as follows: "", [<_a_r_g_1>, <_a_r_g_2>, ..., <_a_r_g_n>] The ffoorrmmaatt is a character string that contains three types of objects defined below: _c_h_a_r_a_c_t_e_r_s Characters that are not _e_s_c_a_p_e _s_e_q_u_e_n_c_e_s or _c_o_n_v_e_r_s_i_o_n _s_p_e_c_i_f_i_c_a_t_i_o_n_s, as described below, are copied to the output. _e_s_c_a_p_e _s_e_q_u_e_n_c_e_s Represent non-graphic characters. _c_o_n_v_e_r_s_i_o_n _s_p_e_c_i_f_i_c_a_t_i_o_n_s 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 ffoorrmmaatt represents one or more blank characters on the output (not _w_h_i_t_e _s_p_a_c_e, which can include newline characters). Therefore, another utility that reads that output as its input must be prepared to parse the data using ssccaannff(3C), aawwkk(1), and so forth. The character is used when exactly one space character is output. EEssccaappee SSeeqquueenncceess The following table lists escape sequences and associated actions on display devices capable of the action. SSeeqquueennccee CChhaarraacctteerr TTeerrmmiinnaall AAccttiioonn ──────────────────────────────────────────────── \\\\ backslash None. \\aa alert Attempts to alert the user through audible or visible notification. \\bb backspace Moves the printing position to one column before the current position, unless the current position is the start of a line. \\ff form-feed Moves the printing position to the initial printing position of the next logical page. \\nn newline Moves the printing position to the start of the next line. \\rr carriage-return Moves the printing position to the start of the current line. \\tt 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. \\vv 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. CCoonnvveerrssiioonn SSppeecciiffiiccaattiioonnss Each conversion specification is introduced by the percent-sign character (%). After the character %, the following appear in sequence: _f_l_a_g_s Zero or more _f_l_a_g_s, in any order, that modify the meaning of the conversion specification. _f_i_e_l_d _w_i_d_t_h An optional string of decimal digits to specify a minimum _f_i_e_l_d _w_i_d_t_h. 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). _p_r_e_c_i_s_i_o_n 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. _c_o_n_v_e_r_s_i_o_n _c_h_a_r_a_c_t_e_r_s A conversion character (see below) that indicates the type of conversion to be applied. _f_l_a_g_s The _f_l_a_g_s 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 −). _<_s_p_a_c_e_> 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. CCoonnvveerrssiioonn CChhaarraacctteerrss 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 _c_o_n_v_e_r_s_i_o_n _c_h_a_r_a_c_t_e_r_s 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 [[−]]_d_d_d_d. The x conversion uses the numbers and letters 0123456789abcdef and the X conversion uses the numbers and letters 0123456789ABCDEF. The _p_r_e_c_i_s_i_o_n 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 pprriinnttff(3C) function in that they can be surrounded with blank characters. This was done so that, given a format such as: "%d\n",<_f_o_o> the implementation could use a pprriinnttff(()) call such as: printf("%6d\n", _f_o_o); and still conform. This notation is thus somewhat like ssccaannff(()) in addition to pprriinnttff(()).. _f The floating point number argument is written in decimal notation in the style [[−]]_d_d_d._d_d_d, where the number of digits after the radix character (shown here as a decimal point) is equal to the _p_r_e_c_i_s_i_o_n specification. The LLCC__NNUUMMEERRIICC locale category determines the radix character to use in this format. If the _p_r_e_c_i_s_i_o_n is omitted from the argument, six digits are written after the radix character; if the _p_r_e_c_i_s_i_o_n is explicitly 0, no radix character appears. _e_,_E The floating point number argument is written in the style [[−]]_d._d_d_de±dddd (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 LLCC__NNUUMMEERRIICC 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 uunnssiiggnneedd cchhaarr 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 _p_r_e_c_i_s_i_o_n 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 _f_i_e_l_d _w_i_d_t_h 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 _f_i_e_l_d _w_i_d_t_h should not be confused with the term _p_r_e_c_i_s_i_o_n used in the description of %s. One difference from the C function pprriinnttff(()) is that the l and h conversion characters are not used. There is no differentiation between decimal values for type iinntt, type lloonngg, or type sshhoorrtt. 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 (ffllooaatt or ddoouubbllee in C). These are simply referred to as floating point numbers. Many of the output descriptions use the term lliinnee, such as: "%s", <_i_n_p_u_t _l_i_n_e> Since the definition of lliinnee includes the trailing newline character already, there is no need to include a \\nn in the format; a double newline character would otherwise result. EEXXAAMMPPLLEESS EExxaammppllee 11 To represent the output of a program that prints a date and time in the form Sunday, July 3, 10:02, where _<_w_e_e_k_d_a_y_> and _<_m_o_n_t_h_> are strings: "%s,/\%s/\%d,/\%d:%.2d\n",<_w_e_e_k_d_a_y>,<_m_o_n_t_h>,<_d_a_y>,<_h_o_u_r>,<_m_i_n> EExxaammppllee 22 To show pi written to 5 decimal places: "pi/\=/\%.5f\n",<_v_a_l_u_e _o_f _p_i> EExxaammppllee 33 To show an input file format consisting of five colon- separated fields: "%s:%s:%s:%s:%s\n",<_a_r_g_1>,<_a_r_g_2>,<_a_r_g_3>,<_a_r_g_4>,<_a_r_g_5> SSEEEE AALLSSOO aawwkk(1), pprriinnttff(1), pprriinnttff(3C), ssccaannff(3C) March 28, 1995 FORMATS(7)