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