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