1.\" $NetBSD: printf.1,v 1.25 2014/04/13 01:45:34 snj Exp $ 2.\" 3.\" Copyright (c) 1989, 1990, 1993 4.\" The Regents of the University of California. 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 8.1 (Berkeley) 6/6/93 34.\" 35.Dd May 6, 2008 36.Dt PRINTF 1 37.Os 38.Sh NAME 39.Nm printf 40.Nd formatted output 41.Sh SYNOPSIS 42.Nm 43.Ar format 44.Op Ar arguments ... 45.Sh DESCRIPTION 46.Nm 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 59.Ar arguments 60after the first are treated as strings if the corresponding format is 61either 62.Cm b , 63.Cm B , 64.Cm c , 65or 66.Cm s ; 67otherwise it is evaluated as a C constant, with the following extensions: 68.Pp 69.Bl -bullet -offset indent -compact 70.It 71A leading plus or minus sign is allowed. 72.It 73If the leading character is a single or double quote, the value is the 74.Tn ASCII 75code of the next character. 76.El 77.Pp 78The format string is reused as often as necessary to satisfy the 79.Ar arguments . 80Any extra format specifications are evaluated with zero or the null 81string. 82.Pp 83Character escape sequences are in backslash notation as defined in 84.St -ansiC . 85The characters and their meanings are as follows: 86.Bl -tag -width Ds -offset indent 87.It Cm \ee 88Write an 89.Aq escape 90character. 91.It Cm \ea 92Write a 93.Aq bell 94character. 95.It Cm \eb 96Write a 97.Aq backspace 98character. 99.It Cm \ef 100Write a 101.Aq form-feed 102character. 103.It Cm \en 104Write a 105.Aq new-line 106character. 107.It Cm \er 108Write a 109.Aq carriage return 110character. 111.It Cm \et 112Write a 113.Aq tab 114character. 115.It Cm \ev 116Write a 117.Aq vertical tab 118character. 119.It Cm \e\' 120Write a 121.Aq single quote 122character. 123.It Cm \e" 124Write a 125.Aq double quote 126character. 127.It Cm \e\e 128Write a backslash character. 129.It Cm \e Ns Ar num 130Write an 8\-bit character whose 131.Tn ASCII 132value is the 1\-, 2\-, or 3\-digit octal number 133.Ar num . 134.It Cm \ex Ns Ar xx 135Write an 8\-bit character whose 136.Tn ASCII 137value is the 1\- or 2\-digit hexadecimal number 138.Ar xx . 139.El 140.Pp 141Each format specification is introduced by the percent character 142.Pq Dq \&% . 143The remainder of the format specification includes, 144in the following order: 145.Bl -tag -width Ds 146.It Zero or more of the following flags : 147.Bl -tag -width Ds 148.It Cm # 149A 150.Sq # 151character specifying that the value should be printed in an 152.Dq alternative form . 153For 154.Cm b , 155.Cm c , 156.Cm d , 157and 158.Cm s 159formats, this option has no effect. 160For the 161.Cm o 162format the precision of the number is increased to force the first 163character of the output string to a zero. 164For the 165.Cm x 166.Pq Cm X 167format, a non-zero result has the string 168.Li 0x 169.Pq Li 0X 170prepended to it. 171For 172.Cm e , 173.Cm E , 174.Cm f , 175.Cm g , 176and 177.Cm G 178formats, the result will always contain a decimal point, even if no 179digits follow the point (normally, a decimal point only appears in the 180results of those formats if a digit follows the decimal point). 181For 182.Cm g 183and 184.Cm G 185formats, trailing zeros are not removed from the result as they 186would otherwise be. 187.\" I turned this off - decided it isn't a valid use of '#' 188.\" For the 189.\" .Cm B 190.\" format, backslash-escape sequences are expanded first; 191.It Cm \&\- 192A minus sign 193.Sq \- 194which specifies 195.Em left adjustment 196of the output in the indicated field; 197.It Cm \&+ 198A 199.Sq \&+ 200character specifying that there should always be 201a sign placed before the number when using signed formats. 202.It Sq \&\ \& 203A space specifying that a blank should be left before a positive number 204for a signed format. 205A 206.Sq \&+ 207overrides a space if both are used; 208.It Cm \&0 209A zero `0' character indicating that zero-padding should be used 210rather than blank-padding. 211A 212.Sq \- 213overrides a 214.Sq \&0 215if both are used; 216.El 217.It Field Width : 218An optional digit string specifying a 219.Em field width ; 220if the output string has fewer characters than the field width it will 221be blank-padded on the left (or right, if the left-adjustment indicator 222has been given) to make up the field width (note that a leading zero 223is a flag, but an embedded zero is part of a field width); 224.It Precision : 225An optional period, 226.Sq Cm \&. , 227followed by an optional digit string giving a 228.Em precision 229which specifies the number of digits to appear after the decimal point, 230for 231.Cm e 232and 233.Cm f 234formats, or the maximum number of characters to be printed 235from a string 236.Sm off 237.Pf ( Cm b , 238.Sm on 239.Cm B , 240and 241.Cm s 242formats); if the digit string is missing, the precision is treated 243as zero; 244.It Format : 245A character which indicates the type of format to use (one of 246.Cm diouxXfwEgGbBcs ) . 247.El 248.Pp 249A field width or precision may be 250.Sq Cm \&* 251instead of a digit string. 252In this case an 253.Ar argument 254supplies the field width or precision. 255.Pp 256The format characters and their meanings are: 257.Bl -tag -width Fl 258.It Cm diouXx 259The 260.Ar argument 261is printed as a signed decimal (d or i), unsigned octal, unsigned decimal, 262or unsigned hexadecimal (X or x), respectively. 263.It Cm f 264The 265.Ar argument 266is printed in the style 267.Sm off 268.Pf [\-]ddd Cm \&. No ddd 269.Sm on 270where the number of d's 271after the decimal point is equal to the precision specification for 272the argument. 273If the precision is missing, 6 digits are given; if the precision 274is explicitly 0, no digits and no decimal point are printed. 275.It Cm eE 276The 277.Ar argument 278is printed in the style 279.Sm off 280.Pf [\-]d Cm \&. No ddd Cm e No \*(Pmdd 281.Sm on 282where there 283is one digit before the decimal point and the number after is equal to 284the precision specification for the argument; when the precision is 285missing, 6 digits are produced. 286An upper-case E is used for an 287.Sq E 288format. 289.It Cm gG 290The 291.Ar argument 292is printed in style 293.Cm f 294or in style 295.Cm e 296.Pq Cm E 297whichever gives full precision in minimum space. 298.It Cm b 299Characters from the string 300.Ar argument 301are printed with backslash-escape sequences expanded. 302.Pp 303The following additional backslash-escape sequences are supported: 304.Bl -tag -width Ds 305.It Cm \ec 306Causes 307.Nm 308to ignore any remaining characters in the string operand containing it, 309any remaining string operands, and any additional characters in 310the format operand. 311.It Cm \e0 Ns Ar num 312Write an 8\-bit character whose 313.Tn ASCII 314value is the 1\-, 2\-, or 3\-digit 315octal number 316.Ar num . 317.It Cm \e^ Ns Ar c 318Write the control character 319.Ar c . 320Generates characters `\e000' through `\e037`, and `\e177' (from `\e^?'). 321.It Cm \eM\- Ns Ar c 322Write the character 323.Ar c 324with the 8th bit set. 325Generates characters `\e241' through `\e376`. 326.It Cm \eM^ Ns Ar c 327Write the control character 328.Ar c 329with the 8th bit set. 330Generates characters `\e200' through `\e237`, and `\e377' (from `\eM^?'). 331.El 332.It Cm B 333Characters from the string 334.Ar argument 335are printed with unprintable characters backslash-escaped using the 336.Sm off 337.Pf ` Cm \e Ar c No ', 338.Pf ` Cm \e^ Ar c No ', 339.Pf ` Cm \eM\- Ar c No ' 340or 341.Pf ` Cm \eM^ Ar c No ', 342.Sm on 343formats described above. 344.It Cm c 345The first character of 346.Ar argument 347is printed. 348.It Cm s 349Characters from the string 350.Ar argument 351are printed until the end is reached or until the number of characters 352indicated by the precision specification is reached; if the 353precision is omitted, all characters in the string are printed. 354.It Cm \&% 355Print a `%'; no argument is used. 356.El 357.Pp 358In no case does a non-existent or small field width cause truncation of 359a field; padding takes place only if the specified field width exceeds 360the actual width. 361.Sh EXIT STATUS 362.Ex -std 363.Sh SEE ALSO 364.Xr echo 1 , 365.Xr printf 3 , 366.Xr vis 3 , 367.Xr printf 9 368.Sh STANDARDS 369The 370.Nm 371utility conforms to 372.St -p1003.1-2001 . 373.Pp 374Support for the floating point formats and `*' as a field width and precision 375are optional in POSIX. 376.Pp 377The behaviour of the %B format and the \e', \e", \exxx, \ee and 378\e[M][\-|^]c escape sequences are undefined in POSIX. 379.Sh BUGS 380Since the floating point numbers are translated from 381.Tn ASCII 382to floating-point and 383then back again, floating-point precision may be lost. 384.Pp 385Hexadecimal character constants are restricted to, and should be specified 386as, two character constants. 387This is contrary to the ISO C standard but 388does guarantee detection of the end of the constant. 389.Sh NOTES 390All formats which treat the 391.Ar argument 392as a number first convert the 393.Ar argument 394from its external representation as a character string 395to an internal numeric representation, and then apply the 396format to the internal numeric representation, producing 397another external character string representation. 398One might expect the 399.Cm \&%c 400format to do likewise, but in fact it does not. 401.Pp 402To convert a string representation of a decimal, octal, or hexadecimal 403number into the corresponding character, two nested 404.Nm 405invocations may be used, in which the inner invocation 406converts the input to an octal string, and the outer 407invocation uses the octal string as part of a format. 408For example, the following command outputs the character whose code 409is 0x0A, which is a newline in ASCII: 410.Pp 411.Dl printf \&"$(printf \&"\e\e%o" \&"0x0A")" 412