1.\" $NetBSD: printf.1,v 1.41 2024/11/24 12:33:31 kre 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 November 24, 2024 36.Dt PRINTF 1 37.Os 38.Sh NAME 39.Nm printf 40.Nd formatted output 41.Sh SYNOPSIS 42.Nm 43.Op Fl L 44.Ar format 45.Op Ar argument ... 46.Sh DESCRIPTION 47.Nm 48formats and prints its 49.Ar argument Ns s , 50under control of the 51.Ar format . 52The 53.Ar format 54is a character string which contains three types of objects: 55plain characters, which are simply copied to standard output, 56character escape sequences which are converted and copied to the 57standard output, 58and format specifications, each of which causes printing of the next 59successive 60.Ar argument . 61Each 62.Ar argument 63is used only once. 64.Pp 65If the first character of 66.Ar format 67is a dash 68.Pq Sq Fl , 69.Ar format 70must (and always may) be preceded by a word consisting of 71two dashes 72.Pq Sq Fl Fl 73to prevent it 74from being interpreted as an option string. 75See 76.Xr getopt 3 . 77.Pp 78The 79.Fl L 80option causes all floating point values resulting from format 81conversions to be printed using 82.Vt long double 83formats, rather than the default 84.Vt double . 85.Pp 86The 87.Ar argument Ns s 88after the first are treated as strings if the corresponding format is 89either 90.Cm b , 91.Cm B , 92.Cm c , 93or 94.Cm s ; 95otherwise each is evaluated as a C\~constant, with the following extensions: 96.Bl -bullet -offset indent 97.It 98A leading plus or minus sign is allowed. 99.It 100If the leading character is a single or double quote, 101as part of the 102.Ar argument 103rather than just quoting it for the shell, 104the value is the code of the character following that quote character. 105No further characters are permitted. 106.El 107.Pp 108The format string is reused as often as necessary to satisfy the 109.Ar arguments . 110Any extra format specifications are evaluated with zero or the null 111string. 112.Pp 113Character escape sequences are in backslash notation as defined in 114.St -ansiC . 115The characters and their meanings are as follows: 116.Bl -tag -offset indent -width Cm 117.It Cm \ea 118Write a 119.Aq bell 120character. 121.It Cm \eb 122Write a 123.Aq backspace 124character. 125.It Cm \ee 126Write an 127.Aq escape 128character. 129.It Cm \ef 130Write a 131.Aq form-feed 132character. 133.It Cm \en 134Write a 135.Aq new-line 136character. 137.It Cm \er 138Write a 139.Aq carriage return 140character. 141.It Cm \et 142Write a 143.Aq tab 144character. 145.It Cm \ev 146Write a 147.Aq vertical tab 148character. 149.It Cm \e\(aq 150Write a 151.Aq single quote 152character. 153.It Cm \e\*q 154Write a 155.Aq double quote 156character. 157.It Cm \e\e 158Write a backslash character. 159.It Cm \e Ns Ar num 160Write an 8-bit character whose ASCII 161value is the 1-, 2-, or 3-digit octal number 162.Ar num . 163.It Cm \ex Ns Ar XX 164Write an 8-bit character whose ASCII 165value is the 1- or 2-digit hexadecimal number 166.Ar XX . 167.El 168.Pp 169Each format specification is introduced by the percent character 170.Pq Ql \&% . 171To produce a literal percent 172.Pq Ql \&% 173in the output, write the percent character twice: 174.Pq Ql \&%% . 175This is not a format conversion, 176but a special escape sequence, 177and consumes no 178.Ar argument Ns s . 179The remainder of the format specification includes, 180in the following order: 181.Bl -tag -width 5n 182.It Zero or more of the following unordered flags : 183.Bl -tag -width Cm 184.It Cm # 185A 186.Ql \&# 187character specifying that the value should be printed in an 188.Dq alternative form . 189For 190.Cm b , 191.Cm c , 192.Cm C , 193.Cm d , 194and 195.Cm s 196formats, this option has no effect. 197For the 198.Cm o 199format the precision of the number is increased to cause the first 200character of the numeric output string to be a zero. 201For the 202.Cm x 203.Pq Cm X 204format, a non-zero result has the string 205.Ql 0x 206.Pq Ql 0X 207prepended to it. 208For 209.Cm e , 210.Cm E , 211.Cm f , 212.Cm F , 213.Cm g , 214and 215.Cm G 216formats, the result will always contain a decimal point, even if no 217digits follow the point (normally, a decimal point only appears in the 218results of those formats if a digit follows the decimal point). 219For 220.Cm g 221and 222.Cm G 223formats, trailing zeros are not removed from the result as they 224would otherwise be. 225.\" I turned this off - decided it isn't a valid use of '#' 226.\" For the 227.\" .Cm B 228.\" format, backslash-escape sequences are expanded first; 229.It Cm \&\- 230A minus sign which specifies 231.Em left adjustment 232of the output in the indicated field; 233.It Cm \&+ 234A plus sign which specifies that there should always be 235a sign 236.Po Sq Cm \&+ 237or 238.Sq Cm \&\- 239.Pc 240placed before the number when using signed formats; 241.It Sq Cm \&\ \& 242A 243.Aq space 244character which specifies that a space should be left in the 245position a minus sign would otherwise appear, before 246a non-negative number for a signed format. 247A 248.Ql Cm \&+ 249overrides a 250.Aq space 251if both are used; 252.It Cm \&0 253A digit zero character which specifies that zero-padding should be used 254rather than space-padding to the left of right adjusted fields. 255In this case, a sign 256.Po Sq Cm \&+ , 257.Sq Cm \&\- 258or 259.Sq Cm \&\ \& 260.Pc , 261if included, precedes the padding. 262Padding to the right of left adjusted fields always uses spaces. 263A 264.Ql \- 265overrides a 266.Ql \&0 267if both are used; 268.El 269.Pp 270Specifying a flag more than once is not an error, but has no additional effect. 271.It Field Width : 272An optional digit string specifying a 273.Em field width ; 274if the output string has fewer bytes than the field width it will 275be padded on the left (or right, if the left-adjustment indicator 276has been given) to make up the field width 277(note that a leading zero is a flag, 278but a zero appearing after another digit is part of a field width); 279.It Precision : 280An optional period 281.Pq Ql \&. , 282followed by an optional digit string giving a 283.Em precision 284which specifies the number of digits to appear after the decimal point, 285for 286.Cm e 287and 288.Cm f 289formats, or the maximum number of bytes to be printed 290from a string 291.Sm off 292.Pf ( Cm b , 293.Sm on 294.Cm B , 295and 296.Cm s 297formats); if the digit string is missing, the precision is treated 298as zero; 299.It Format : 300A character which indicates the type of format to use (one of 301.Cm diouxXfFeEgGaAbBcCs ) . 302.El 303.Pp 304A field width or precision may be 305.Sq Cm \&* 306instead of a digit string. 307In this case the next 308.Ar argument , 309preceding the value to be converted, 310supplies the field width or precision. 311It must be an unsigned integer constant. 312If both the field width and precision are 313.Sq Cm \&* 314then two 315.Ar argument Ns s 316are required, with the field width preceding the precision, 317and the value to be converted following those. 318.Pp 319The format characters and their meanings are: 320.Bl -tag -width Fl 321.It Cm diouXx 322The 323.Ar argument , 324which must represent an integer constant, 325with an optional leading plus or minus sign, 326is printed as a signed decimal 327.Cm ( d 328or 329.Cm i ) , 330unsigned octal 331.Cm ( o ) , 332unsigned decimal 333.Cm ( u ) , 334or unsigned hexadecimal 335.Cm ( X 336or 337.Cm x ) . 338.It Cm fF 339The 340.Ar argument 341is printed in the style 342.Oo Li \&\- Oc Ns Ar \&\^ddd Ns Li \&\^\&. Ns Ar ddd 343where the number of 344.Ar d Ns \|'s 345after the decimal point is equal to the precision specification for 346the argument. 347If the precision is missing, 6 digits are given; if the precision 348is explicitly 0, no digits and no decimal point are printed. 349If the number is Infinity, or Not-a-Number, then 350.Ql inf 351or 352.Ql nan 353is printed for 354.Cm f 355format, and 356.Ql INF 357or 358.Ql NAN 359for 360.Cm F 361format. 362.It Cm eE 363The 364.Ar argument 365is printed in the style 366.Oo Li \&\- Oc Ns Ar \&\^d Ns Li \&. Ns Ar ddd Ns Li \&\|e\*(Pm Ns Ar \&\|dd 367where there 368is one digit before the decimal point and the number after is equal to 369the precision specification for the argument; when the precision is 370missing, 6 digits are produced. 371An upper-case 372.Ql E 373is used for an 374.Cm E 375format, and upper-case for Infinity and NaN as for 376.Cm F 377format. 378.It Cm gG 379The 380.Ar argument 381is printed in style 382.Cm f 383.Pq Cm F 384or in style 385.Cm e 386.Pq Cm E 387whichever gives full precision in minimum space. 388.It Cm aA 389The 390.Ar argument 391is treated as a floating point number, 392for which the underlying hexadecimal representation is 393printed. 394See 395.Xr printf 3 396for the details. 397.It Cm b 398Characters from the string 399.Ar argument 400are printed with backslash-escape sequences expanded. 401.Pp 402The following additional backslash-escape sequences are supported: 403.Bl -tag -width Cm 404.It Cm \ec 405Causes 406.Nm 407to ignore any remaining characters in the string operand containing it, 408any remaining operands, and any additional characters in 409the format operand. 410.It Cm \e0 Ns Ar num 411Write an 8-bit character whose ASCII value is the 1-, 2-, or 4123-digit octal number 413.Ar num . 414.It Cm \e^ Ns Ar c 415Write the control character 416.Ar c . 417Generates characters 418.Sq \e000 419through 420.Sq \e037 , 421and 422.Sq \e177 423(from 424.Ql \e^\&? ) . 425.It Cm \eM^ Ns Ar c 426Write the control character 427.Ar c 428with the 8th bit set. 429Generates characters 430.Sq \e200 431through 432.Sq \e237 , 433and 434.Sq \e377 435(from 436.Ql \eM^\&? ) . 437.It Cm \eM\- Ns Ar c 438Write the character 439.Ar c 440with the 8th bit set. 441Generates characters 442.Sq \e240 443through 444.Sq \e376 . 445.El 446.It Cm B 447Characters from the string 448.Ar argument 449are printed with unprintable characters backslash-escaped using the 450.Sq Cm \e Ns Ar c , 451.Sq Cm \e^ Ns Ar c , 452.Sq Cm \eM^ Ns Ar c , 453or 454.Sq Cm \eM\- Ns Ar c 455formats described above. 456.It Cm c 457The first character of the next 458.Ar argument 459is printed. 460.It Cm C 461The 462.Ar argument , 463which must represent an integer constant, 464with an optional leading plus or minus sign, 465is treated as a wide character code point, and printed. 466.It Cm s 467Characters from the string 468.Ar argument 469are printed until the end is reached or until the number of bytes 470indicated by the precision specification is reached; if the 471precision is omitted, all characters in the string are printed. 472.El 473.Pp 474In no case does a non-existent or small field width cause truncation of 475a field; padding takes place only if the specified field width exceeds 476the actual width. 477.Pp 478If an argument required by a format string is present, but is not in 479a format expected by the format string conversion, a warning will be 480printed to standard error, identifying the argument by number 481.Pq 1 is the first after the format string 482and usually also by content. 483In such a case a value will still be produced, and printed, 484and processing will continue, but 485.Nm 486will eventually exit with a failure status. 487.Sh EXIT STATUS 488.Ex -std 489.Sh SEE ALSO 490.Xr echo 1 , 491.Xr printf 3 , 492.Xr vis 3 , 493.Xr printf 9 494.Sh STANDARDS 495The 496.Nm 497utility conforms to 498.St -p1003.1-2001 . 499.Pp 500Support for the floating point formats and 501.Sq Cm \&* 502as a field width and precision 503are optional in POSIX. 504.Pp 505The behaviour of the 506.Cm \&%B 507and 508.Cm \&%C 509formats and the 510.Cm \e\(aq , 511.Cm \e\*q , 512.Cm \ee , 513.Cm \ex Ns Ar XX , 514and 515.Cm \e Ns Oo Cm M Oc Ns Oo Cm \- Ns Li \&\(or Ns Cm ^ Oc Ns Ar c 516escape sequences are undefined in POSIX. 517.Sh BUGS 518Since the floating point numbers are translated from ASCII to 519floating-point and then back again, floating-point precision may be lost. 520.Pp 521Hexadecimal character constants given as escapes in strings are 522restricted to, and should be specified as, two hexadecimal characters. 523This is contrary to the ISO C standard but 524does guarantee detection of the end of the constant. 525.Sh NOTES 526All formats which treat the 527.Ar argument 528as a number first convert the 529.Ar argument 530from its external representation as a character string 531to an internal numeric representation, and then apply the 532format to the internal numeric representation, producing 533another external character string representation. 534One might expect the 535.Cm \&%c 536format to do likewise, but in fact it does not. 537.Pp 538To convert a string representation of a decimal, octal, or hexadecimal 539number into the corresponding character, 540using a portable invocation, 541two nested 542.Nm 543invocations may be used, in which the inner invocation 544converts the input to an octal string, and the outer 545invocation uses the octal string as part of a format. 546For example, the following command outputs the character whose code 547is 0x0a, which is a newline in ASCII: 548.Pp 549.Dl printf \*q$(printf \(aq\e\e%o\(aq 0x0a)\*q 550.Pp 551In this implementation of 552.Nm 553it is possible to achieve the same result using one invocation: 554.Pp 555.Dl printf %C 0x0a 556