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