1.\" $OpenBSD: printf.1,v 1.29 2015/02/28 21:51:57 bentley 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: February 28 2015 $ 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, the value is the 70.Tn ASCII 71code of the next character. 72.El 73.Pp 74The format string is reused as often as necessary to satisfy the 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 79.St -ansiC . 80The characters and their meanings are 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 \ee 88Write an <escape> 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 an 8-bit character whose 105.Tn ASCII 106value is the 1-, 2-, or 3-digit 107octal number 108.Ar num . 109.El 110.Pp 111Each format specification is introduced by the percent 112.Pq Sq \&% 113character. 114The remainder of the format specifiers include, 115in the following order: 116.Bl -tag -width Ds 117.It "Zero or more of the following flags:" 118.Bl -tag -width Ds 119.It Cm # 120Specifies that the value should be printed in an 121.Dq alternate form . 122For the 123.Cm o 124format the precision of the number is increased to force the first 125character of the output string to a zero. 126For the 127.Cm x 128.Pq Cm X 129format, a non-zero result has the string 130.Li 0x 131.Pq Li 0X 132prepended to it. 133For 134.Cm a , 135.Cm A , 136.Cm e , 137.Cm E , 138.Cm f , 139.Cm F , 140.Cm 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. 152For all other formats, behaviour is undefined. 153.It Cm \&\- 154Specifies the 155.Em left adjustment 156of the output in the indicated field. 157.It Cm \&+ 158Specifies that there should always be 159a sign placed before the number when using signed formats. 160.It Sq \&\ \& 161A space specifies that a blank should be left before a positive number 162for a signed format. 163A 164.Ql + 165overrides a space if both are used. 166.It Cm \&0 167A zero character specifies that zero-padding should be used 168rather than blank-padding. 169This flag is ignored if used with a precision 170specifier and any of the 171.Cm d , i , o , u , 172or 173.Cm x 174.Pq Cm X 175formats. 176A 177.Ql \&- 178overrides a 179.Ql \&0 180if both are used. 181.El 182.It "Field Width:" 183An optional digit string specifying a 184.Em field width ; 185if the output string has fewer characters than the field width it will 186be blank-padded on the left (or right, if the left-adjustment indicator 187has been given) to make up the field width (note that a leading zero 188is a flag, but an embedded zero is part of a field width). 189.It Precision: 190An optional period 191.Pq Sq \&. , 192followed by an optional digit string giving a 193.Em precision 194which specifies the number of digits to appear after the decimal point, 195for 196.Cm e 197and 198.Cm f 199formats, or the maximum number of characters to be printed 200from a string; if the digit string is missing, the precision is treated 201as zero. 202.It Format: 203A character which indicates the type of format to use (one of 204.Cm diouxXfFeEgGaAbcs ) . 205.El 206.Pp 207A field width or precision may be 208.Ql \&* 209instead of a digit string. 210In this case an 211.Ar argument 212supplies the field width or precision. 213.Pp 214The format characters and their meanings are: 215.Bl -tag -width Fl 216.It Cm diouXx 217The 218.Ar argument 219is printed as a signed decimal 220.Pq Cm d No or Cm i , 221unsigned octal, unsigned decimal, 222or unsigned hexadecimal 223.Pq Cm x No or Cm X , 224respectively. 225.It Cm fF 226The 227.Ar argument 228is printed in the style 229.Sm off 230.Pf [\-]ddd Cm \&. No ddd 231.Sm on 232where the number of d's 233after the decimal point is equal to the precision specification for 234the argument. 235If the precision is missing, 6 digits are given; if the precision 236is explicitly 0, no digits and no decimal point are printed. 237.Pp 238If the argument is infinity, it will be converted to [-]inf 239.Pq Cm f 240or [-]INF 241.Pq Cm F , 242respectively. 243If the argument is not-a-number (NaN), it will be converted to 244[-]nan 245.Pq Cm f 246or [-]NAN 247.Pq Cm F , 248respectively. 249.It Cm eE 250The 251.Ar argument 252is printed in the style 253.Sm off 254.Pf [\-]d Cm \&. No ddd Cm e No \(+-dd 255.Sm on 256where there 257is one digit before the decimal point and the number after is equal to 258the precision specification for the argument; when the precision is 259missing, 6 digits are produced. 260An upper-case 261.Sq E 262is used for an 263.Cm E 264format. 265.Pp 266If the argument is infinity, it will be converted to [-]inf 267.Pq Cm e 268or [-]INF 269.Pq Cm E , 270respectively. 271If the argument is not-a-number (NaN), it will be converted to 272[-]nan 273.Pq Cm e 274or [-]NAN 275.Pq Cm E , 276respectively. 277.It Cm gG 278The 279.Ar argument 280is printed in style 281.Cm f 282or in style 283.Cm e 284.Pq Cm E 285whichever gives full precision in minimum space. 286.Pp 287If the argument is infinity, it will be converted to [-]inf 288.Pq Cm g 289or [-]INF 290.Pq Cm G , 291respectively. 292If the argument is not-a-number (NaN), it will be converted to 293[-]nan 294.Pq Cm g 295or [-]NAN 296.Pq Cm G , 297respectively. 298.It Cm aA 299The 300.Ar argument 301is printed in style 302.Sm off 303.Pf [\-]0xh Cm \&. No hhh Cm p No [\(+-]d 304.Sm on 305where there is one digit before the hexadecimal point and the number 306after is equal to the precision specification for the argument. 307When the precision is missing, enough digits are produced to convey 308the argument's exact double-precision floating-point representation. 309.Pp 310If the argument is infinity, it will be converted to [-]inf 311.Pq Cm a 312or [-]INF 313.Pq Cm A , 314respectively. 315If the argument is not-a-number (NaN), it will be converted to 316[-]nan 317.Pq Cm a 318or [-]NAN 319.Pq Cm A , 320respectively. 321.It Cm b 322Characters from the string 323.Ar argument 324are printed with backslash-escape sequences expanded. 325If the 326.Ar argument 327contains the special escape sequence 328.Cm \ec , 329this escape sequence is discarded together with 330all remaining characters in this argument, all further arguments, 331and all remaining characters in the 332.Ar format 333string. 334.It Cm c 335The first character of 336.Ar argument 337is printed. 338.It Cm s 339Characters from the string 340.Ar argument 341are printed until the end is reached or until the number of characters 342indicated by the precision specification is reached; however if the 343precision is 0 or missing, all characters in the string are printed. 344.It Cm \&% 345Print a 346.Ql \&% ; 347no argument is used. 348.El 349.Pp 350In no case does a non-existent or small field width cause truncation of 351a field; padding takes place only if the specified field width exceeds 352the actual width. 353.Sh EXIT STATUS 354.Ex -std printf 355.Sh EXAMPLES 356Convert a hexadecimal value to decimal and print it out: 357.Pp 358.D1 Ic $ printf \&"%d\en\&" 0x20 359.Pp 360Print the decimal representation of the character 'a' (see 361.Xr ascii 7 ) : 362.Pp 363.D1 Ic $ printf \&"%d\en\&" \e'a 364.Sh SEE ALSO 365.Xr echo 1 , 366.Xr printf 3 367.Sh STANDARDS 368The 369.Nm 370utility is compliant with the 371.St -p1003.1-2008 372specification. 373.Pp 374The escape sequences \ee and \e' are extensions to that specification. 375.Sh HISTORY 376The 377.Nm 378command appeared in 379.Bx 4.3 Reno . 380.Sh CAVEATS 381It is important never to pass a string with user-supplied data as a 382format without using 383.Ql %s . 384An attacker can put format specifiers in the string to mangle your stack, 385leading to a possible security hole. 386.Pp 387Always be sure to use the proper secure idiom: 388.Bd -literal -offset indent 389printf "%s" "$STRING" 390.Ed 391.Sh BUGS 392Since arguments are translated from 393.Tn ASCII 394to floating-point, and 395then back again, floating-point precision may be lost. 396