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