1.\" $NetBSD: printf.1,v 1.19 2003/04/28 09:38:19 wiz 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. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the University of 20.\" California, Berkeley and its contributors. 21.\" 4. Neither the name of the University nor the names of its contributors 22.\" may be used to endorse or promote products derived from this software 23.\" without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 26.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 27.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 28.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 29.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 30.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 31.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 32.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 33.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 34.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 35.\" SUCH DAMAGE. 36.\" 37.\" from: @(#)printf.1 8.1 (Berkeley) 6/6/93 38.\" 39.Dd November 5, 1993 40.Dt PRINTF 1 41.Os 42.Sh NAME 43.Nm printf 44.Nd formatted output 45.Sh SYNOPSIS 46.Nm 47.Ar format 48.Op Ar arguments ... 49.Sh DESCRIPTION 50.Nm 51formats and prints its arguments, after the first, under control 52of the 53.Ar format . 54The 55.Ar format 56is a character string which contains three types of objects: plain characters, 57which are simply copied to standard output, character escape sequences which 58are converted and copied to the standard output, and format specifications, 59each of which causes printing of the next successive 60.Ar argument . 61.Pp 62The 63.Ar arguments 64after the first are treated as strings if the corresponding format is 65either 66.Cm b , 67.Cm B , 68.Cm c , 69or 70.Cm s ; 71otherwise it is evaluated as a C constant, with the following extensions: 72.Pp 73.Bl -bullet -offset indent -compact 74.It 75A leading plus or minus sign is allowed. 76.It 77If the leading character is a single or double quote, the value is the 78.Tn ASCII 79code of the next character. 80.El 81.Pp 82The format string is reused as often as necessary to satisfy the 83.Ar arguments . 84Any extra format specifications are evaluated with zero or the null 85string. 86.Pp 87Character escape sequences are in backslash notation as defined in 88.St -ansiC . 89The characters and their meanings are as follows: 90.Bl -tag -width Ds -offset indent 91.It Cm \ee 92Write an 93.Aq escape 94character. 95.It Cm \ea 96Write a 97.Aq bell 98character. 99.It Cm \eb 100Write a 101.Aq backspace 102character. 103.It Cm \ef 104Write a 105.Aq form-feed 106character. 107.It Cm \en 108Write a 109.Aq new-line 110character. 111.It Cm \er 112Write a 113.Aq carriage return 114character. 115.It Cm \et 116Write a 117.Aq tab 118character. 119.It Cm \ev 120Write a 121.Aq vertical tab 122character. 123.It Cm \e\' 124Write a 125.Aq single quote 126character. 127.It Cm \e" 128Write a 129.Aq double quote 130character. 131.It Cm \e\e 132Write a backslash character. 133.It Cm \e Ns Ar num 134Write an 8\-bit character whose 135.Tn ASCII 136value is the 1\-, 2\-, or 3\-digit octal number 137.Ar num . 138.It Cm \ex Ns Ar xx 139Write an 8\-bit character whose 140.Tn ASCII 141value is the 1\- or 2\-digit hexadecimal number 142.Ar xx . 143.El 144.Pp 145Each format specification is introduced by the percent character 146.Pq Dq \&% . 147The remainder of the format specification includes, 148in the following order: 149.Bl -tag -width Ds 150.It Zero or more of the following flags : 151.Bl -tag -width Ds 152.It Cm # 153A 154.Sq # 155character specifying that the value should be printed in an 156.Dq alternative form . 157For 158.Cm b , 159.Cm c , 160.Cm d , 161and 162.Cm s 163formats, this option has no effect. 164For the 165.Cm o 166format the precision of the number is increased to force the first 167character of the output string to a zero. 168For the 169.Cm x 170.Pq Cm X 171format, a non-zero result has the string 172.Li 0x 173.Pq Li 0X 174prepended to it. 175For 176.Cm e , 177.Cm E , 178.Cm f , 179.Cm g , 180and 181.Cm G 182formats, the result will always contain a decimal point, even if no 183digits follow the point (normally, a decimal point only appears in the 184results of those formats if a digit follows the decimal point). 185For 186.Cm g 187and 188.Cm G 189formats, trailing zeros are not removed from the result as they 190would otherwise be. 191.\" I turned this off - decided it isn't a valid use of '#' 192.\" For the 193.\" .Cm B 194.\" format, backslash-escape sequences are expanded first; 195.It Cm \&\- 196A minus sign 197.Sq \- 198which specifies 199.Em left adjustment 200of the output in the indicated field; 201.It Cm \&+ 202A 203.Sq \&+ 204character specifying that there should always be 205a sign placed before the number when using signed formats. 206.It Sq \&\ \& 207A space specifying that a blank should be left before a positive number 208for a signed format. 209A 210.Sq \&+ 211overrides a space if both are used; 212.It Cm \&0 213A zero `0' character indicating that zero-padding should be used 214rather than blank-padding. 215A 216.Sq \- 217overrides a 218.Sq \&0 219if both are used; 220.El 221.It Field Width : 222An optional digit string specifying a 223.Em field width ; 224if the output string has fewer characters than the field width it will 225be blank-padded on the left (or right, if the left-adjustment indicator 226has been given) to make up the field width (note that a leading zero 227is a flag, but an embedded zero is part of a field width); 228.It Precision : 229An optional period, 230.Sq Cm \&. , 231followed by an optional digit string giving a 232.Em precision 233which specifies the number of digits to appear after the decimal point, 234for 235.Cm e 236and 237.Cm f 238formats, or the maximum number of characters to be printed 239from a string 240.Sm off 241.Pf ( Cm b , 242.Sm on 243.Cm B , 244and 245.Cm s 246formats); if the digit string is missing, the precision is treated 247as zero; 248.It Format : 249A character which indicates the type of format to use (one of 250.Cm diouxXfwEgGbBcs ) . 251.El 252.Pp 253A field width or precision may be 254.Sq Cm \&* 255instead of a digit string. 256In this case an 257.Ar argument 258supplies the field width or precision. 259.Pp 260The format characters and their meanings are: 261.Bl -tag -width Fl 262.It Cm diouXx 263The 264.Ar argument 265is printed as a signed decimal (d or i), unsigned octal, unsigned decimal, 266or unsigned hexadecimal (X or x), respectively. 267.It Cm f 268The 269.Ar argument 270is printed in the style 271.Sm off 272.Pf [\-]ddd Cm \&. No ddd 273.Sm on 274where the number of d's 275after the decimal point is equal to the precision specification for 276the argument. 277If the precision is missing, 6 digits are given; if the precision 278is explicitly 0, no digits and no decimal point are printed. 279.It Cm eE 280The 281.Ar argument 282is printed in the style 283.Sm off 284.Pf [\-]d Cm \&. No ddd Cm e No \\*(Pmdd 285.Sm on 286where there 287is one digit before the decimal point and the number after is equal to 288the precision specification for the argument; when the precision is 289missing, 6 digits are produced. 290An upper-case E is used for an 291.Sq E 292format. 293.It Cm gG 294The 295.Ar argument 296is printed in style 297.Cm f 298or in style 299.Cm e 300.Pq Cm E 301whichever gives full precision in minimum space. 302.It Cm b 303Characters from the string 304.Ar argument 305are printed with backslash-escape sequences expanded. 306.br 307The following additional backslash-escape sequences are supported: 308.Bl -tag -width Ds 309.It Cm \ec 310Causes 311.Nm 312to ignore any remaining characters in the string operand containing it, 313any remaining string operands, and any additional characters in 314the format operand. 315.It Cm \e0 Ns Ar num 316Write an 8\-bit character whose 317.Tn ASCII 318value is the 1\-, 2\-, or 3\-digit 319octal number 320.Ar num . 321.It Cm \e^ Ns Ar c 322Write the control character 323.Ar c . 324Generates characters `\e000' through `\e037`, and `\e177' (from `\e^?'). 325.It Cm \eM\- Ns Ar c 326Write the character 327.Ar c 328with the 8th bit set. 329Generates characters `\e241' through `\e376`. 330.It Cm \eM^ Ns Ar c 331Write the control character 332.Ar c 333with the 8th bit set. 334Generates characters `\e000' through `\e037`, and `\e177' (from `\eM^?'). 335.El 336.It Cm B 337Characters from the string 338.Ar argument 339are printed with unprintable characters backslash-escaped using the 340.Sm off 341.Pf ` Cm \e Ar c No ', 342.Pf ` Cm \e^ Ar c No ', 343.Pf ` Cm \eM\- Ar c No ' 344or 345.Pf ` Cm \eM^ Ar c No ', 346.Sm on 347formats described above. 348.It Cm c 349The first character of 350.Ar argument 351is printed. 352.It Cm s 353Characters from the string 354.Ar argument 355are printed until the end is reached or until the number of characters 356indicated by the precision specification is reached; if the 357precision is omitted, all characters in the string are printed. 358.It Cm \&% 359Print a `%'; no argument is used. 360.El 361.Pp 362In no case does a non-existent or small field width cause truncation of 363a field; padding takes place only if the specified field width exceeds 364the actual width. 365.Sh EXIT STATUS 366.Nm 367exits 0 on success, 1 on failure. 368.Sh SEE ALSO 369.Xr echo 1 , 370.Xr printf 3 , 371.Xr vis 3 , 372.Xr printf 9 373.Sh STANDARDS 374The 375.Nm 376utility conforms to 377.St -p1003.1-2001 . 378.Pp 379Support for the floating point formats and `*' as a field width and precision 380are optional in POSIX. 381.Pp 382The behaviour of the %B format and the \e', \e", \exxx, \ee and 383\e[M][\-|^]c escape sequences are undefined in POSIX. 384.Sh BUGS 385Since the floating point numbers are translated from 386.Tn ASCII 387to floating-point and 388then back again, floating-point precision may be lost. 389.Pp 390Hexadecimal character constants are restricted to, and should be specified 391as, two character constants. 392This is contrary to the ISO C standard but 393does guarantee detection of the end of the constant. 394