1.\" Copyright (c) 1989, 1990, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" the Institute of Electrical and Electronics Engineers, Inc. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)printf.1 8.1 (Berkeley) 6/6/93 32.\" 33.Dd July 1, 2020 34.Dt PRINTF 1 35.Os 36.Sh NAME 37.Nm printf 38.Nd formatted output 39.Sh SYNOPSIS 40.Nm 41.Ar format Op Ar arguments ... 42.Sh DESCRIPTION 43The 44.Nm 45utility formats and prints its arguments, after the first, under control 46of the 47.Ar format . 48The 49.Ar format 50is a character string which contains three types of objects: plain characters, 51which are simply copied to standard output, character escape sequences which 52are converted and copied to the standard output, and format specifications, 53each of which causes printing of the next successive 54.Ar argument . 55.Pp 56The 57.Ar arguments 58after the first are treated as strings if the corresponding format is 59either 60.Cm c , b 61or 62.Cm s ; 63otherwise it is evaluated as a C constant, with the following extensions: 64.Pp 65.Bl -bullet -offset indent -compact 66.It 67A leading plus or minus sign is allowed. 68.It 69If the leading character is a single or double quote, the value is the 70character code of the next character. 71.El 72.Pp 73The format string is reused as often as necessary to satisfy the 74.Ar arguments . 75Any extra format specifications are evaluated with zero or the null 76string. 77.Pp 78Character escape sequences are in backslash notation as defined in the 79.St -ansiC , 80with extensions. 81The characters and their meanings 82are as follows: 83.Pp 84.Bl -tag -width Ds -offset indent -compact 85.It Cm \ea 86Write a <bell> character. 87.It Cm \eb 88Write a <backspace> character. 89.It Cm \ef 90Write a <form-feed> character. 91.It Cm \en 92Write a <new-line> character. 93.It Cm \er 94Write a <carriage return> character. 95.It Cm \et 96Write a <tab> character. 97.It Cm \ev 98Write a <vertical tab> character. 99.It Cm \e\' 100Write a <single quote> character. 101.It Cm \e\e 102Write a backslash character. 103.It Cm \e Ns Ar num 104Write a byte whose 105value is the 1-, 2-, or 3-digit 106octal number 107.Ar num . 108Multibyte characters can be constructed using multiple 109.Cm \e Ns Ar num 110sequences. 111.El 112.Pp 113Each format specification is introduced by the percent character 114(``%''). 115The remainder of the format specification includes, 116in the following order: 117.Bl -tag -width Ds 118.It "Zero or more of the following flags:" 119.Bl -tag -width Ds 120.It Cm # 121A `#' character 122specifying that the value should be printed in an ``alternate form''. 123For 124.Cm b , c , d , s 125and 126.Cm u 127formats, this option has no effect. 128For the 129.Cm o 130formats the precision of the number is increased to force the first 131character of the output string to a zero. 132For the 133.Cm x 134.Pq Cm X 135format, a non-zero result has the string 136.Li 0x 137.Pq Li 0X 138prepended to it. 139For 140.Cm a , A , e , E , f , F , g 141and 142.Cm G 143formats, the result will always contain a decimal point, even if no 144digits follow the point (normally, a decimal point only appears in the 145results of those formats if a digit follows the decimal point). 146For 147.Cm g 148and 149.Cm G 150formats, trailing zeros are not removed from the result as they 151would otherwise be; 152.It Cm \&\- 153A minus sign `\-' which specifies 154.Em left adjustment 155of the output in the indicated field; 156.It Cm \&+ 157A `+' character specifying that there should always be 158a sign placed before the number when using signed formats. 159.It Sq \&\ \& 160A space specifying that a blank should be left before a positive number 161for a signed format. 162A `+' overrides a space if both are used; 163.It Cm \&0 164A zero `0' character indicating that zero-padding should be used 165rather than blank-padding. 166A `\-' overrides a `0' if both are used; 167.El 168.It "Field Width:" 169An optional digit string specifying a 170.Em field width ; 171if the output string has fewer bytes than the field width it will 172be blank-padded on the left (or right, if the left-adjustment indicator 173has been given) to make up the field width (note that a leading zero 174is a flag, but an embedded zero is part of a field width); 175.It Precision: 176An optional period, 177.Sq Cm \&.\& , 178followed by an optional digit string giving a 179.Em precision 180which specifies the number of digits to appear after the decimal point, 181for 182.Cm e 183and 184.Cm f 185formats, or the maximum number of bytes to be printed 186from a string; if the digit string is missing, the precision is treated 187as zero; 188.It Format: 189A character which indicates the type of format to use (one of 190.Cm diouxXfFeEgGaAcsb ) . 191The uppercase formats differ from their lowercase counterparts only in 192that the output of the former is entirely in uppercase. 193The floating-point format specifiers 194.Pq Cm fFeEgGaA 195may be prefixed by an 196.Cm L 197to request that additional precision be used, if available. 198.El 199.Pp 200A field width or precision may be 201.Sq Cm \&* 202instead of a digit string. 203In this case an 204.Ar argument 205supplies the field width or precision. 206.Pp 207The format characters and their meanings are: 208.Bl -tag -width Fl 209.It Cm diouXx 210The 211.Ar argument 212is printed as a signed decimal (d or i), unsigned octal, unsigned decimal, 213or unsigned hexadecimal (X or x), respectively. 214.It Cm fF 215The 216.Ar argument 217is printed in the style `[\-]ddd.ddd' where the number of d's 218after the decimal point is equal to the precision specification for 219the argument. 220If the precision is missing, 6 digits are given; if the precision 221is explicitly 0, no digits and no decimal point are printed. 222The values \*[If] and \*[Na] are printed as 223.Ql inf 224and 225.Ql nan , 226respectively. 227.It Cm eE 228The 229.Ar argument 230is printed in the style 231.Cm e 232.Sm off 233.Sq Op - Ar d.ddd No \(+- Ar dd 234.Sm on 235where there 236is one digit before the decimal point and the number after is equal to 237the precision specification for the argument; when the precision is 238missing, 6 digits are produced. 239The values \*[If] and \*[Na] are printed as 240.Ql inf 241and 242.Ql nan , 243respectively. 244.It Cm gG 245The 246.Ar argument 247is printed in style 248.Cm f 249.Pq Cm F 250or in style 251.Cm e 252.Pq Cm E 253whichever gives full precision in minimum space. 254.It Cm aA 255The 256.Ar argument 257is printed in style 258.Sm off 259.Sq Op - Ar h.hhh No \(+- Li p Ar d 260.Sm on 261where there is one digit before the hexadecimal point and the number 262after is equal to the precision specification for the argument; 263when the precision is missing, enough digits are produced to convey 264the argument's exact double-precision floating-point representation. 265The values \*[If] and \*[Na] are printed as 266.Ql inf 267and 268.Ql nan , 269respectively. 270.It Cm c 271The first byte of 272.Ar argument 273is printed. 274.It Cm s 275Bytes from the string 276.Ar argument 277are printed until the end is reached or until the number of bytes 278indicated by the precision specification is reached; however if the 279precision is 0 or missing, the string is printed entirely. 280.It Cm b 281As for 282.Cm s , 283but interpret character escapes in backslash notation in the string 284.Ar argument . 285The permitted escape sequences are slightly different in that 286octal escapes are 287.Cm \e0 Ns Ar num 288instead of 289.Cm \e Ns Ar num 290and that an additional escape sequence 291.Cm \ec 292stops further output from this 293.Nm 294invocation. 295.It Cm n$ 296Allows reordering of the output according to 297.Ar argument . 298.It Cm \&% 299Print a `%'; no argument is used. 300.El 301.Pp 302The decimal point 303character is defined in the program's locale (category 304.Dv LC_NUMERIC ) . 305.Pp 306In no case does a non-existent or small field width cause truncation of 307a field; padding takes place only if the specified field width exceeds 308the actual width. 309.Pp 310Some shells may provide a builtin 311.Nm 312command which is similar or identical to this utility. 313Consult the 314.Xr builtin 1 315manual page. 316.Sh EXIT STATUS 317.Ex -std 318.Sh EXAMPLES 319Print the string 320.Qq hello : 321.Bd -literal -offset indent 322$ printf "%s\en" hello 323hello 324.Ed 325.Pp 326Same as above, but notice that the format string is not quoted and hence we 327do not get the expected behavior: 328.Bd -literal -offset indent 329$ printf %s\en hello 330hellon$ 331.Ed 332.Pp 333Print arguments forcing sign only for the first argument: 334.Bd -literal -offset indent 335$ printf "%+d\en%d\en%d\en" 1 -2 13 336+1 337-2 33813 339.Ed 340.Pp 341Same as above, but the single format string will be applied to the three 342arguments: 343.Bd -literal -offset indent 344$ printf "%+d\en" 1 -2 13 345+1 346-2 347+13 348.Ed 349.Pp 350Print number using only two digits after the decimal point: 351.Bd -literal -offset indent 352$ printf "%.2f\en" 31.7456 35331.75 354.Ed 355.Sh COMPATIBILITY 356The traditional 357.Bx 358behavior of converting arguments of numeric formats not beginning 359with a digit to the ASCII 360code of the first character is not supported. 361.Sh SEE ALSO 362.Xr builtin 1 , 363.Xr echo 1 , 364.Xr sh 1 , 365.Xr printf 3 366.Sh STANDARDS 367The 368.Nm 369command is expected to be compatible with the 370.St -p1003.2 371specification. 372.Sh HISTORY 373The 374.Nm 375command appeared in 376.Bx 4.3 Reno . 377It is modeled 378after the standard library function, 379.Xr printf 3 . 380.Sh CAVEATS 381ANSI hexadecimal character constants were deliberately not provided. 382.Pp 383Trying to print a dash ("-") as the first character causes 384.Nm 385to interpret the dash as a program argument. 386.Nm -- 387must be used before 388.Ar format . 389.Pp 390If the locale contains multibyte characters 391(such as UTF-8), 392the 393.Cm c 394format and 395.Cm b 396and 397.Cm s 398formats with a precision 399may not operate as expected. 400.Sh BUGS 401Since the floating point numbers are translated from ASCII 402to floating-point and then back again, floating-point precision may be lost. 403(By default, the number is translated to an IEEE-754 double-precision 404value before being printed. 405The 406.Cm L 407modifier may produce additional precision, depending on the hardware platform.) 408.Pp 409The escape sequence \e000 is the string terminator. 410When present in the argument for the 411.Cm b 412format, the argument will be truncated at the \e000 character. 413.Pp 414Multibyte characters are not recognized in format strings (this is only 415a problem if 416.Ql % 417can appear inside a multibyte character). 418