1.\" $OpenBSD: printf.1,v 1.35 2021/05/07 14:31:27 martijn Exp $ 2.\" 3.\" Copyright (c) 1989, 1990 The Regents of the University of California. 4.\" 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 5.11 (Berkeley) 7/24/91 34.\" 35.Dd $Mdocdate: May 7 2021 $ 36.Dt PRINTF 1 37.Os 38.Sh NAME 39.Nm printf 40.Nd formatted output 41.Sh SYNOPSIS 42.Nm printf 43.Ar format 44.Op Ar argument ... 45.Sh DESCRIPTION 46.Nm printf 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 arguments after the first are treated as strings 59if the corresponding format is 60.Cm b , 61.Cm c 62or 63.Cm s ; 64otherwise it is evaluated as a C constant, with the following extensions: 65.Bl -bullet -offset indent 66.It 67A leading plus or minus sign is allowed. 68.It 69If the leading character is a single or double quote, 70the value is the ASCII code of the next character. 71.El 72.Pp 73The format string is reused as often as necessary to satisfy the arguments. 74Any extra format specifications are evaluated with zero or the null 75string. 76.Pp 77Character escape sequences are in backslash notation as defined in 78.St -ansiC . 79The characters and their meanings are as follows: 80.Pp 81.Bl -tag -width Ds -offset indent -compact 82.It Cm \ea 83Write a <bell> character. 84.It Cm \eb 85Write a <backspace> character. 86.It Cm \ee 87Write an <escape> character. 88.It Cm \ef 89Write a <form-feed> character. 90.It Cm \en 91Write a <new-line> character. 92.It Cm \er 93Write a <carriage return> character. 94.It Cm \et 95Write a <tab> character. 96.It Cm \ev 97Write a <vertical tab> character. 98.It Cm \e\(aq 99Write a <single quote> character. 100.It Cm \e\e 101Write a backslash character. 102.It Cm \e Ns Ar num 103Write an 8-bit character whose ASCII value is 104the 1-, 2-, or 3-digit octal number 105.Ar num . 106.It Cm \ex Ns Ar num 107Write an 8-bit character whose ASCII value is 108the 1- or 2-digit hexadecimal 109number 110.Ar num . 111.El 112.Pp 113Each format specification is introduced by the percent 114.Pq Sq \&% 115character. 116The remainder of the format specifiers include, 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 # 122Specifies that the value should be printed in an 123.Dq alternate form . 124For the 125.Cm o 126format the precision of the number is increased to force the first 127character of the output string to a zero. 128For the 129.Cm x 130.Pq Cm X 131format, a non-zero result has the string 132.Li 0x 133.Pq Li 0X 134prepended to it. 135For 136.Cm a , 137.Cm A , 138.Cm e , 139.Cm E , 140.Cm f , 141.Cm F , 142.Cm g , 143and 144.Cm G 145formats, the result will always contain a decimal point, even if no 146digits follow the point (normally, a decimal point only appears in the 147results of those formats if a digit follows the decimal point). 148For 149.Cm g 150and 151.Cm G 152formats, trailing zeros are not removed from the result as they 153would otherwise be. 154For all other formats, behaviour is undefined. 155.It Cm \&\- 156Specifies the 157.Em left adjustment 158of the output in the indicated field. 159.It Cm \&+ 160Specifies that there should always be 161a sign placed before the number when using signed formats. 162.It Sq \&\ \& 163A space specifies that a blank should be left before a positive number 164for a signed format. 165A 166.Ql + 167overrides a space if both are used. 168.It Cm \&0 169A zero character specifies that zero-padding should be used 170rather than blank-padding. 171This flag is ignored if used with a precision 172specifier and any of the 173.Cm d , i , o , u , 174or 175.Cm x 176.Pq Cm X 177formats. 178A 179.Ql \&- 180overrides a 181.Ql \&0 182if both are used. 183.El 184.It "Field Width:" 185An optional digit string specifying a 186.Em field width ; 187if the output string has fewer characters than the field width it will 188be blank-padded on the left (or right, if the left-adjustment indicator 189has been given) to make up the field width (note that a leading zero 190is a flag, but an embedded zero is part of a field width). 191.It Precision: 192An optional period 193.Pq Sq \&. , 194followed by an optional digit string giving a 195.Em precision 196which specifies the number of digits to appear after the decimal point, 197for 198.Cm e 199and 200.Cm f 201formats, or the maximum number of bytes to be printed 202from a string; if the digit string is missing, the precision is treated 203as zero. 204.It Format: 205A character which indicates the type of format to use (one of 206.Cm diouxXfFeEgGaAbcs ) . 207.El 208.Pp 209A field width or precision may be 210.Ql \&* 211instead of a digit string. 212In this case an 213.Ar argument 214supplies the field width or precision. 215.Pp 216The format characters and their meanings are: 217.Bl -tag -width Ds 218.It Cm diouXx 219The 220.Ar argument 221is printed as a signed decimal 222.Pq Cm d No or Cm i , 223unsigned octal, unsigned decimal, 224or unsigned hexadecimal 225.Pq Cm x No or Cm X , 226respectively. 227.It Cm fF 228The 229.Ar argument 230is printed in the style 231.Sm off 232.Pf [\-]ddd Cm \&. No ddd 233.Sm on 234where the number of d's 235after the decimal point is equal to the precision specification for 236the argument. 237If the precision is missing, 6 digits are given; if the precision 238is explicitly 0, no digits and no decimal point are printed. 239.Pp 240If the argument is infinity, it will be converted to [-]inf 241.Pq Cm f 242or [-]INF 243.Pq Cm F , 244respectively. 245If the argument is not-a-number (NaN), it will be converted to 246[-]nan 247.Pq Cm f 248or [-]NAN 249.Pq Cm F , 250respectively. 251.It Cm eE 252The 253.Ar argument 254is printed in the style 255.Sm off 256.Pf [\-]d Cm \&. No ddd Cm e No \(+-dd 257.Sm on 258where there 259is one digit before the decimal point and the number after is equal to 260the precision specification for the argument; when the precision is 261missing, 6 digits are produced. 262An upper-case 263.Sq E 264is used for an 265.Cm E 266format. 267.Pp 268If the argument is infinity, it will be converted to [-]inf 269.Pq Cm e 270or [-]INF 271.Pq Cm E , 272respectively. 273If the argument is not-a-number (NaN), it will be converted to 274[-]nan 275.Pq Cm e 276or [-]NAN 277.Pq Cm E , 278respectively. 279.It Cm gG 280The 281.Ar argument 282is printed in style 283.Cm f 284or in style 285.Cm e 286.Pq Cm E 287whichever gives full precision in minimum space. 288.Pp 289If the argument is infinity, it will be converted to [-]inf 290.Pq Cm g 291or [-]INF 292.Pq Cm G , 293respectively. 294If the argument is not-a-number (NaN), it will be converted to 295[-]nan 296.Pq Cm g 297or [-]NAN 298.Pq Cm G , 299respectively. 300.It Cm aA 301The 302.Ar argument 303is printed in style 304.Sm off 305.Pf [\-]0xh Cm \&. No hhh Cm p No [\(+-]d 306.Sm on 307where there is one digit before the hexadecimal point and the number 308after is equal to the precision specification for the argument. 309When the precision is missing, enough digits are produced to convey 310the argument's exact double-precision floating-point representation. 311.Pp 312If the argument is infinity, it will be converted to [-]inf 313.Pq Cm a 314or [-]INF 315.Pq Cm A , 316respectively. 317If the argument is not-a-number (NaN), it will be converted to 318[-]nan 319.Pq Cm a 320or [-]NAN 321.Pq Cm A , 322respectively. 323.It Cm b 324Characters from the string 325.Ar argument 326are printed with backslash-escape sequences expanded. 327In the 328.Ar argument , 329ASCII characters can be octally encoded either as 330.Cm \e0 Ns Ar num 331or as 332.Cm \e Ns Ar num 333like in the 334.Ar format 335string. 336If the 337.Ar argument 338contains the special escape sequence 339.Cm \ec , 340this escape sequence is discarded together with 341all remaining characters in this argument, all further arguments, 342and all remaining characters in the 343.Ar format 344string. 345.It Cm c 346The first character of 347.Ar argument 348is printed. 349.It Cm s 350Characters from the string 351.Ar argument 352are printed until the end is reached or until the number of bytes 353indicated by the precision specification is reached; however if the 354precision is 0 or missing, all characters in the string are printed. 355.It Cm \&% 356Print a 357.Ql \&% ; 358no argument is used. 359.El 360.Pp 361In no case does a non-existent or small field width cause truncation of 362a field; padding takes place only if the specified field width exceeds 363the actual width. 364.Sh EXIT STATUS 365.Ex -std printf 366.Sh EXAMPLES 367Convert a hexadecimal value to decimal and print it out: 368.Pp 369.Dl $ printf \&"%d\en\&" 0x20 370.Pp 371Print the decimal representation of the character 'a' (see 372.Xr ascii 7 ) : 373.Pp 374.Dl $ printf \&"%d\en\&" \e'a 375.Sh SEE ALSO 376.Xr echo 1 , 377.Xr printf 3 378.Sh STANDARDS 379The 380.Nm 381utility is compliant with the 382.St -p1003.1-2008 383specification, but in order to produce predictable output 384it deliberately ignores the 385.Xr locale 1 386and always operates as if 387.Ev LC_ALL Ns =C 388were set. 389.Pp 390The escape sequences 391.Cm \ee , 392.Cm \ex 393and 394.Cm \e' , 395as well as omitting the leading digit 396.Cm 0 397from 398.Cm \e0 Ns Ar num 399octal escape sequences in 400.Cm %b 401arguments, are extensions to that specification. 402.Sh HISTORY 403The 404.Nm 405command appeared in 406.Bx 4.3 Reno . 407.Sh CAVEATS 408It is important never to pass a string with user-supplied data as a 409format without using 410.Ql %s . 411An attacker can put format specifiers in the string to mangle your stack, 412leading to a possible security hole. 413.Pp 414Always be sure to use the proper secure idiom: 415.Bd -literal -offset indent 416printf "%s" "$STRING" 417.Ed 418.Sh BUGS 419Since arguments are translated from ASCII to floating-point, 420and then back again, floating-point precision may be lost. 421