1.\" $NetBSD: printf.1,v 1.31 2018/08/31 17:27:35 kre Exp $ 2.\" 3.\" Copyright (c) 1989, 1990, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" This code is derived from software contributed to Berkeley by 7.\" the Institute of Electrical and Electronics Engineers, Inc. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. Neither the name of the University nor the names of its contributors 18.\" may be used to endorse or promote products derived from this software 19.\" without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 22.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 24.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 25.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 27.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 28.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 29.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" from: @(#)printf.1 8.1 (Berkeley) 6/6/93 34.\" 35.Dd August 31, 2018 36.Dt PRINTF 1 37.Os 38.Sh NAME 39.Nm printf 40.Nd formatted output 41.Sh SYNOPSIS 42.Nm 43.Ar format 44.Op Ar arguments ... 45.Sh DESCRIPTION 46.Nm 47formats and prints its arguments, after the first, under control 48of the 49.Ar format . 50The 51.Ar format 52is a character string which contains three types of objects: plain characters, 53which are simply copied to standard output, character escape sequences which 54are converted and copied to the standard output, and format specifications, 55each of which causes printing of the next successive 56.Ar argument . 57.Pp 58The 59.Ar arguments 60after the first are treated as strings if the corresponding format is 61either 62.Cm b , 63.Cm B , 64.Cm c , 65or 66.Cm s ; 67otherwise it is evaluated as a C constant, with the following extensions: 68.Pp 69.Bl -bullet -offset indent -compact 70.It 71A leading plus or minus sign is allowed. 72.It 73If the leading character is a single or double quote, the value is the ASCII 74code of the next character. 75.El 76.Pp 77The format string is reused as often as necessary to satisfy the 78.Ar arguments . 79Any extra format specifications are evaluated with zero or the null 80string. 81.Pp 82Character escape sequences are in backslash notation as defined in 83.St -ansiC . 84The characters and their meanings are as follows: 85.Bl -tag -width Ds -offset indent 86.It Cm \ee 87Write an 88.Aq escape 89character. 90.It Cm \ea 91Write a 92.Aq bell 93character. 94.It Cm \eb 95Write a 96.Aq backspace 97character. 98.It Cm \ef 99Write a 100.Aq form-feed 101character. 102.It Cm \en 103Write a 104.Aq new-line 105character. 106.It Cm \er 107Write a 108.Aq carriage return 109character. 110.It Cm \et 111Write a 112.Aq tab 113character. 114.It Cm \ev 115Write a 116.Aq vertical tab 117character. 118.It Cm \e\' 119Write a 120.Aq single quote 121character. 122.It Cm \e" 123Write a 124.Aq double quote 125character. 126.It Cm \e\e 127Write a backslash character. 128.It Cm \e Ns Ar num 129Write an 8\-bit character whose ASCII 130value is the 1\-, 2\-, or 3\-digit octal number 131.Ar num . 132.It Cm \ex Ns Ar xx 133Write an 8\-bit character whose ASCII 134value is the 1\- or 2\-digit hexadecimal number 135.Ar xx . 136.El 137.Pp 138Each format specification is introduced by the percent character 139.Pq Dq \&% . 140The remainder of the format specification includes, 141in the following order: 142.Bl -tag -width Ds 143.It Zero or more of the following flags : 144.Bl -tag -width Ds 145.It Cm # 146A 147.Sq # 148character specifying that the value should be printed in an 149.Dq alternative form . 150For 151.Cm b , 152.Cm c , 153.Cm d , 154and 155.Cm s 156formats, this option has no effect. 157For the 158.Cm o 159format the precision of the number is increased to force the first 160character of the output string to a zero. 161For the 162.Cm x 163.Pq Cm X 164format, a non-zero result has the string 165.Li 0x 166.Pq Li 0X 167prepended to it. 168For 169.Cm e , 170.Cm E , 171.Cm f , 172.Cm F , 173.Cm g , 174and 175.Cm G 176formats, the result will always contain a decimal point, even if no 177digits follow the point (normally, a decimal point only appears in the 178results of those formats if a digit follows the decimal point). 179For 180.Cm g 181and 182.Cm G 183formats, trailing zeros are not removed from the result as they 184would otherwise be. 185.\" I turned this off - decided it isn't a valid use of '#' 186.\" For the 187.\" .Cm B 188.\" format, backslash-escape sequences are expanded first; 189.It Cm \&\- 190A minus sign 191.Sq \- 192which specifies 193.Em left adjustment 194of the output in the indicated field; 195.It Cm \&+ 196A 197.Sq \&+ 198character specifying that there should always be 199a sign placed before the number when using signed formats. 200.It Sq \&\ \& 201A space specifying that a blank should be left before a positive number 202for a signed format. 203A 204.Sq \&+ 205overrides a space if both are used; 206.It Cm \&0 207A zero `0' character indicating that zero-padding should be used 208rather than blank-padding. 209A 210.Sq \- 211overrides a 212.Sq \&0 213if both are used; 214.El 215.It Field Width : 216An optional digit string specifying a 217.Em field width ; 218if the output string has fewer characters than the field width it will 219be blank-padded on the left (or right, if the left-adjustment indicator 220has been given) to make up the field width (note that a leading zero 221is a flag, but an embedded zero is part of a field width); 222.It Precision : 223An optional period, 224.Sq Cm \&. , 225followed by an optional digit string giving a 226.Em precision 227which specifies the number of digits to appear after the decimal point, 228for 229.Cm e 230and 231.Cm f 232formats, or the maximum number of characters to be printed 233from a string 234.Sm off 235.Pf ( Cm b , 236.Sm on 237.Cm B , 238and 239.Cm s 240formats); if the digit string is missing, the precision is treated 241as zero; 242.It Format : 243A character which indicates the type of format to use (one of 244.Cm diouxXfFeEgGaAbBcs ) . 245.El 246.Pp 247A field width or precision may be 248.Sq Cm \&* 249instead of a digit string. 250In this case an 251.Ar argument 252supplies the field width or precision. 253.Pp 254The format characters and their meanings are: 255.Bl -tag -width Fl 256.It Cm diouXx 257The 258.Ar argument , 259which must represent an integer constant, 260with an optional leading plus or minus sign, 261is printed as a signed decimal (d or i), 262unsigned octal (o), unsigned decimal (u), 263or unsigned hexadecimal (X or x). 264.It Cm fF 265The 266.Ar argument 267is printed in the style 268.Sm off 269.Pf [\-]ddd Cm \&. No ddd 270.Sm on 271where the number of d's 272after the decimal point is equal to the precision specification for 273the argument. 274If the precision is missing, 6 digits are given; if the precision 275is explicitly 0, no digits and no decimal point are printed. 276If the number is Infinity, or Not a Number (NaN), then 277.Dq inf 278.Pq \&or Dq nan 279is printed for 280.Cm f 281format, and 282.Dq INF 283.Pq \&or Dq NAN 284for 285.Cm F 286format. 287.It Cm eE 288The 289.Ar argument 290is printed in the style 291.Sm off 292.Pf [\-]d Cm \&. No ddd Cm e No \*(Pmdd 293.Sm on 294where there 295is one digit before the decimal point and the number after is equal to 296the precision specification for the argument; when the precision is 297missing, 6 digits are produced. 298An upper-case E is used for an 299.Sq E 300format, and upper-case for Infinity and NaN as for 301.Sq F 302format. 303.It Cm gG 304The 305.Ar argument 306is printed in style 307.Cm f 308.Pq Cm F 309or in style 310.Cm e 311.Pq Cm E 312whichever gives full precision in minimum space. 313.It Cm aA 314The 315.Ar argument 316is treated as a floating point number, 317for which the underlying hexadecimal representation is 318printed. 319See 320.Xr printf 3 321for the details. 322.It Cm b 323Characters from the string 324.Ar argument 325are printed with backslash-escape sequences expanded. 326.Pp 327The following additional backslash-escape sequences are supported: 328.Bl -tag -width Ds 329.It Cm \ec 330Causes 331.Nm 332to ignore any remaining characters in the string operand containing it, 333any remaining string operands, and any additional characters in 334the format operand. 335.It Cm \e0 Ns Ar num 336Write an 8\-bit character whose ASCII value is the 1\-, 2\-, or 3373\-digit octal number 338.Ar num . 339.It Cm \e^ Ns Ar c 340Write the control character 341.Ar c . 342Generates characters `\e000' through `\e037`, and `\e177' (from `\e^?'). 343.It Cm \eM\- Ns Ar c 344Write the character 345.Ar c 346with the 8th bit set. 347Generates characters `\e241' through `\e376`. 348.It Cm \eM^ Ns Ar c 349Write the control character 350.Ar c 351with the 8th bit set. 352Generates characters `\e200' through `\e237`, and `\e377' (from `\eM^?'). 353.El 354.It Cm B 355Characters from the string 356.Ar argument 357are printed with unprintable characters backslash-escaped using the 358.Sm off 359.Pf ` Cm \e Ar c No ', 360.Pf ` Cm \e^ Ar c No ', 361.Pf ` Cm \eM\- Ar c No ' 362or 363.Pf ` Cm \eM^ Ar c No ', 364.Sm on 365formats described above. 366.It Cm c 367The first character of 368.Ar argument 369is printed. 370.It Cm s 371Characters from the string 372.Ar argument 373are printed until the end is reached or until the number of characters 374indicated by the precision specification is reached; if the 375precision is omitted, all characters in the string are printed. 376.It Cm \&% 377Print a `%'; no argument is used. 378.El 379.Pp 380In no case does a non-existent or small field width cause truncation of 381a field; padding takes place only if the specified field width exceeds 382the actual width. 383.Pp 384If the first character of 385.Ar format 386is a dash, 387.Ar format 388must be preceded by a word consisting of two dashes (--) to prevent it 389from being interpreted as an option string. 390.Sh EXIT STATUS 391.Ex -std 392.Sh SEE ALSO 393.Xr echo 1 , 394.Xr printf 3 , 395.Xr vis 3 , 396.Xr printf 9 397.Sh STANDARDS 398The 399.Nm 400utility conforms to 401.St -p1003.1-2001 . 402.Pp 403Support for the floating point formats and `*' as a field width and precision 404are optional in POSIX. 405.Pp 406The behaviour of the %B format and the \e', \e", \exxx, \ee and 407\e[M][\-|^]c escape sequences are undefined in POSIX. 408.Sh BUGS 409Since the floating point numbers are translated from ASCII to 410floating-point and then back again, floating-point precision may be lost. 411.Pp 412Hexadecimal character constants are restricted to, and should be specified 413as, two character constants. 414This is contrary to the ISO C standard but 415does guarantee detection of the end of the constant. 416.Sh NOTES 417All formats which treat the 418.Ar argument 419as a number first convert the 420.Ar argument 421from its external representation as a character string 422to an internal numeric representation, and then apply the 423format to the internal numeric representation, producing 424another external character string representation. 425One might expect the 426.Cm \&%c 427format to do likewise, but in fact it does not. 428.Pp 429To convert a string representation of a decimal, octal, or hexadecimal 430number into the corresponding character, two nested 431.Nm 432invocations may be used, in which the inner invocation 433converts the input to an octal string, and the outer 434invocation uses the octal string as part of a format. 435For example, the following command outputs the character whose code 436is 0x0A, which is a newline in ASCII: 437.Pp 438.Dl printf \&"$(printf \&"\e\e%o" \&"0x0A")" 439