1 '\" te
   2 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
   3 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
   4 .\" Copyright 1992, X/Open Company Limited All Rights Reserved
   5 .\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
   6 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   7 .\" permission to reproduce portions of its copyrighted documentation.
   8 .\" Original documentation from The Open Group can be obtained online at
   9 .\" http://www.opengroup.org/bookstore/.
  10 .\" The Institute of Electrical and Electronics Engineers and The Open Group,
  11 .\" have given us permission to reprint portions of their documentation. In the
  12 .\" following statement, the phrase "this text" refers to portions of the
  13 .\" system documentation. Portions of this text are reprinted and reproduced in
  14 .\" electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004
  15 .\" Edition, Standard for Information Technology -- Portable Operating System
  16 .\" Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright
  17 .\" (C) 2001-2004 by the Institute of Electrical and Electronics Engineers,
  18 .\" Inc and The Open Group. In the event of any discrepancy between these
  19 .\" versions and the original IEEE and The Open Group Standard, the original
  20 .\" IEEE and The Open Group Standard is the referee document. The original
  21 .\" Standard can be obtained online at
  22 .\" http://www.opengroup.org/unix/online.html.
  23 .\" This notice shall appear on any product containing this material.
  24 .\" The contents of this file are subject to the terms of the Common
  25 .\" Development and Distribution License (the "License").  You may not use this
  26 .\" file except in compliance with the License.
  27 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or
  28 .\" http://www.opensolaris.org/os/licensing.  See the License for the specific
  29 .\" language governing permissions and limitations under the License.
  30 .\" When distributing Covered Code, include this CDDL HEADER in each file and
  31 .\" include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable,
  32 .\" add the following below this CDDL HEADER, with the fields enclosed by
  33 .\" brackets "[]" replaced with your own identifying information:
  34 .\" Portions Copyright [yyyy] [name of copyright owner]
  35 .TH PRINTF 1 "May 11, 2014"
  36 .SH NAME
  37 printf \- write formatted output
  38 .SH SYNOPSIS
  39 .SS "/usr/bin/printf"
  40 .LP
  41 .nf
  42 \fBprintf\fR \fIformat\fR [\fIargument\fR]...
  43 .fi
  44 
  45 .SS "ksh93"
  46 .LP
  47 .nf
  48 \fBprintf\fR \fIformat\fR [\fIstring\fR...]
  49 .fi
  50 
  51 .SH DESCRIPTION
  52 .SS "/usr/bin/printf"
  53 .sp
  54 .LP
  55 The \fBprintf\fR utility writes each string operand to standard output using
  56 \fIformat\fR to control the output format.
  57 .SH OPERANDS
  58 .SS "/usr/bin/printf"
  59 .sp
  60 .LP
  61 The following operands are supported by \fB/usr/bin/printf\fR:
  62 .sp
  63 .ne 2
  64 .na
  65 \fB\fIformat\fR\fR
  66 .ad
  67 .RS 12n
  68 A string describing the format to use to write the remaining operands. The
  69 \fIformat\fR operand is used as the \fIformat\fR string described on the
  70 \fBformats\fR(5) manual page, with the following exceptions:
  71 .RS +4
  72 .TP
  73 .ie t \(bu
  74 .el o
  75 A \fBSPACE\fR character in the format string, in any context other than a flag
  76 of a conversion specification, is treated as an ordinary character that is
  77 copied to the output.
  78 .RE
  79 .RS +4
  80 .TP
  81 .ie t \(bu
  82 .el o
  83 A character in the format string is treated as a character, not as a
  84 \fBSPACE\fR character.
  85 .RE
  86 .RS +4
  87 .TP
  88 .ie t \(bu
  89 .el o
  90 In addition to the escape sequences described on the \fBformats\fR(5) manual
  91 page (\fB\e\e\fR, \fB\ea\fR, \fB\eb\fR, \fB\ef\fR, \fB\en\fR, \fB\er\fR,
  92 \fB\et\fR, \fB\ev\fR), \fB\e\fR\fIddd\fR, where \fIddd\fR is a one-, two- or
  93 three-digit octal number, is written as a byte with the numeric value specified
  94 by the octal number.
  95 .RE
  96 .RS +4
  97 .TP
  98 .ie t \(bu
  99 .el o
 100 The program does not precede or follow output from the \fBd\fR or \fBu\fR
 101 conversion specifications with blank characters not specified by the
 102 \fIformat\fR operand.
 103 .RE
 104 .RS +4
 105 .TP
 106 .ie t \(bu
 107 .el o
 108 The program does not precede output from the \fBo\fR conversion specification
 109 with zeros not specified by the \fIformat\fR operand.
 110 .RE
 111 .RS +4
 112 .TP
 113 .ie t \(bu
 114 .el o
 115 The argument used for the conversion character (or width or precision
 116 parameters, see below) may be taken from the \fIn\fRnth argument instead
 117 of the next unused argument, by specifying \fIn\fR\fB$\fR immediately following
 118 the \fB%\fR character, or the \fB*\fR character (for width or precision
 119 arguments).
 120 If \fIn\fR\fB$\fR appears in any conversions in the format string,
 121 then it must be used for all conversions, including any variable width or
 122 precision specifiers.
 123 .RE
 124 .RS +4
 125 .TP
 126 .ie t \(bu
 127 .el o
 128 The special character \fB*\fR may be used instead of a string of decimal digits
 129 to indicate a minimum field width or a precision.  In this case the next
 130 available argument is used (or the \fIn\fRth if the form \fIn\fR\fB$\fR is
 131 used), treating its value as a decimal string.
 132 .RE
 133 .RS +4
 134 .TP
 135 .ie t \(bu
 136 .el o
 137 An additional conversion character, \fBb\fR, is supported as follows. The
 138 argument is taken to be a string that can contain backslash-escape sequences.
 139 The following backslash-escape sequences are supported:
 140 .RS +4
 141 .TP
 142 .ie t \(bu
 143 .el o
 144 the escape sequences listed on the \fBformats\fR(5) manual page (\fB\e\e\fR,
 145 \fB\ea\fR, \fB\eb\fR, \fB\ef\fR, \fB\en\fR, \fB\er\fR, \fB\et\fR, \fB\ev\fR),
 146 which are converted to the characters they represent
 147 .RE
 148 .RS +4
 149 .TP
 150 .ie t \(bu
 151 .el o
 152 \fB\e0\fR\fIddd\fR, where \fIddd\fR is a zero-, one-, two- or three-digit octal
 153 number that is converted to a byte with the numeric value specified by the
 154 octal number
 155 .RE
 156 .RS +4
 157 .TP
 158 .ie t \(bu
 159 .el o
 160 \fB\ec\fR, which is written and causes \fBprintf\fR to ignore any remaining
 161 characters in the string operand containing it, any remaining string operands
 162 and any additional characters in the \fIformat\fR operand.
 163 .RE
 164 .RE
 165 The interpretation of a backslash followed by any other sequence of characters
 166 is unspecified.
 167 .sp
 168 Bytes from the converted string are written until the end of the string or the
 169 number of bytes indicated by the precision specification is reached. If the
 170 precision is omitted, it is taken to be infinite, so all bytes up to the end of
 171 the converted string are written. For each specification that consumes an
 172 argument, the next argument operand is evaluated and converted to the
 173 appropriate type for the conversion as specified below. The \fIformat\fR
 174 operand is reused as often as necessary to satisfy the argument operands. Any
 175 extra \fBc\fR or \fBs\fR conversion specifications are evaluated as if a null
 176 string argument were supplied; other extra conversion specifications are
 177 evaluated as if a zero argument were supplied.
 178 .sp
 179 When there are more argument operands than format specifiers, and the
 180 format includes \fIn\fR\fB$\fR position indicators, then the format is
 181 reprocessed from the beginning as above, but with the argument list starting
 182 from the next argument after the highest \fIn\fRth argument previously
 183 encountered.
 184 .sp
 185 If the \fIformat\fR operand
 186 contains no conversion specifications and \fIargument\fR operands are present,
 187 the results are unspecified. If a character sequence in the \fIformat\fR
 188 operand begins with a \fB%\fR character, but does not form a valid conversion
 189 specification, the behavior is unspecified.
 190 .RE
 191 
 192 .sp
 193 .ne 2
 194 .na
 195 \fB\fIargument\fR\fR
 196 .ad
 197 .RS 12n
 198 The strings to be written to standard output, under the control of
 199 \fBformat\fR. The \fIargument\fR operands are treated as strings if the
 200 corresponding conversion character is \fBb\fR, \fBc\fR or \fBs\fR. Otherwise,
 201 it is evaluated as a C constant, as described by the ISO C standard, with the
 202 following extensions:
 203 .RS +4
 204 .TP
 205 .ie t \(bu
 206 .el o
 207 A leading plus or minus sign is allowed.
 208 .RE
 209 .RS +4
 210 .TP
 211 .ie t \(bu
 212 .el o
 213 If the leading character is a single- or double-quote, the value is the numeric
 214 value in the underlying codeset of the character following the single- or
 215 double-quote.
 216 .RE
 217 If an argument operand cannot be completely converted into an internal value
 218 appropriate to the corresponding conversion specification, a diagnostic message
 219 is written to standard error and the utility does not exit with a zero exit
 220 status, but continues processing any remaining operands and writes the value
 221 accumulated at the time the error was detected to standard output.
 222 .RE
 223 
 224 .SS "ksh93"
 225 .sp
 226 .LP
 227 The \fIformat\fR operands support the full range of ANSI C/C99/XPG6 formatting
 228 specifiers as well as additional specifiers:
 229 .sp
 230 .ne 2
 231 .na
 232 \fB\fB%b\fR\fR
 233 .ad
 234 .RS 6n
 235 Each character in the string operand is processed specially, as follows:
 236 .sp
 237 .ne 2
 238 .na
 239 \fB\fB\ea\fR\fR
 240 .ad
 241 .RS 8n
 242 Alert character.
 243 .RE
 244 
 245 .sp
 246 .ne 2
 247 .na
 248 \fB\fB\eb\fR\fR
 249 .ad
 250 .RS 8n
 251 Backspace character.
 252 .RE
 253 
 254 .sp
 255 .ne 2
 256 .na
 257 \fB\fB\ec\fR\fR
 258 .ad
 259 .RS 8n
 260 Terminate output without appending NEWLINE. The remaining string operands are
 261 ignored.
 262 .RE
 263 
 264 .sp
 265 .ne 2
 266 .na
 267 \fB\fB\eE\fR\fR
 268 .ad
 269 .RS 8n
 270 Escape character (\fBASCII\fR octal \fB033\fR).
 271 .RE
 272 
 273 .sp
 274 .ne 2
 275 .na
 276 \fB\fB\ef\fR\fR
 277 .ad
 278 .RS 8n
 279 FORM FEED character.
 280 .RE
 281 
 282 .sp
 283 .ne 2
 284 .na
 285 \fB\fB\en\fR\fR
 286 .ad
 287 .RS 8n
 288 NEWLINE character.
 289 .RE
 290 
 291 .sp
 292 .ne 2
 293 .na
 294 \fB\fB\et\fR\fR
 295 .ad
 296 .RS 8n
 297 TAB character.
 298 .RE
 299 
 300 .sp
 301 .ne 2
 302 .na
 303 \fB\fB\ev\fR\fR
 304 .ad
 305 .RS 8n
 306 Vertical tab character.
 307 .RE
 308 
 309 .sp
 310 .ne 2
 311 .na
 312 \fB\fB\e\e\fR\fR
 313 .ad
 314 .RS 8n
 315 Backslash character.
 316 .RE
 317 
 318 .sp
 319 .ne 2
 320 .na
 321 \fB\fB\e0\fR\fIx\fR\fR
 322 .ad
 323 .RS 8n
 324 The 8-bit character whose \fBASCII\fR code is the \fB1\fR-, \fB2\fR-, or
 325 \fB3\fR-digit octal number \fIx\fR.
 326 .RE
 327 
 328 .RE
 329 
 330 .sp
 331 .ne 2
 332 .na
 333 \fB\fB%B\fR\fR
 334 .ad
 335 .RS 6n
 336 Treat the argument as a variable name and output the value without converting
 337 it to a string. This is most useful for variables of type \fB-b\fR.
 338 .RE
 339 
 340 .sp
 341 .ne 2
 342 .na
 343 \fB\fB%H\fR\fR
 344 .ad
 345 .RS 6n
 346 Output string with characters \fB<\fR, \fB&\fR, \fB>\fR, \fB"\fR, and
 347 non-printable characters, properly escaped for use in HTML and XML documents.
 348 .RE
 349 
 350 .sp
 351 .ne 2
 352 .na
 353 \fB\fB%P\fR\fR
 354 .ad
 355 .RS 6n
 356 Treat \fIstring\fR as an extended regular expression and convert it to a shell
 357 pattern.
 358 .RE
 359 
 360 .sp
 361 .ne 2
 362 .na
 363 \fB\fB%q\fR\fR
 364 .ad
 365 .RS 6n
 366 Output \fIstring\fR quoted in a manner that it can be read in by the shell to
 367 get back the same string. However, empty strings resulting from missing string
 368 operands are not quoted.
 369 .RE
 370 
 371 .sp
 372 .ne 2
 373 .na
 374 \fB\fB%R\fR\fR
 375 .ad
 376 .RS 6n
 377 Treat \fIstring\fR as an shell pattern expression and convert it to an extended
 378 regular expression.
 379 .RE
 380 
 381 .sp
 382 .ne 2
 383 .na
 384 \fB\fB%T\fR\fR
 385 .ad
 386 .RS 6n
 387 Treat \fIstring\fR as a date/time string and format it. The \fBT\fR can be
 388 preceded by (\fIdformat\fR), where \fIdformat\fR is a date format as defined by
 389 the \fBdate\fR(1) command.
 390 .RE
 391 
 392 .sp
 393 .ne 2
 394 .na
 395 \fB\fB%Z\fR\fR
 396 .ad
 397 .RS 6n
 398 Output a byte whose value is \fB0\fR.
 399 .RE
 400 
 401 .sp
 402 .LP
 403 When performing conversions of \fIstring\fR to satisfy a numeric format
 404 specifier, if the first character of \fIstring\fR is \fB"or'\fR, the value is
 405 the numeric value in the underlying code set of the character following the
 406 \fB"or'\fR. Otherwise, \fIstring\fR is treated like a shell arithmetic
 407 expression and evaluated.
 408 .sp
 409 .LP
 410 If a \fIstring\fR operand cannot be completely converted into a value
 411 appropriate for that format specifier, an error occurs, but remaining
 412 \fIstring\fR operands continue to be processed.
 413 .sp
 414 .LP
 415 In addition to the format specifier extensions, the following extensions of
 416 ANSI C/C99/XPG6 are permitted in format specifiers:
 417 .RS +4
 418 .TP
 419 .ie t \(bu
 420 .el o
 421 The escape sequences \fB\eE\fR and \fB\ee\fR expand to the escape character
 422 which is octal 033 in ASCII.
 423 .RE
 424 .RS +4
 425 .TP
 426 .ie t \(bu
 427 .el o
 428 The escape sequence \fB\ecx\fR expands to CTRL-x.
 429 .RE
 430 .RS +4
 431 .TP
 432 .ie t \(bu
 433 .el o
 434 The escape sequence \fB\eC[.\fR\fIname\fR\fB\&.]\fR expands to the collating
 435 element \fIname\fR.
 436 .RE
 437 .RS +4
 438 .TP
 439 .ie t \(bu
 440 .el o
 441 The escape sequence \fB\ex{hex}\fR expands to the character corresponding to
 442 the hexadecimal value \fBhex\fR.
 443 .RE
 444 .RS +4
 445 .TP
 446 .ie t \(bu
 447 .el o
 448 The format modifier flag = can be used to center a field to a specified width.
 449 When the output is a terminal, the character width is used rather than the
 450 number of bytes.
 451 .RE
 452 .RS +4
 453 .TP
 454 .ie t \(bu
 455 .el o
 456 Each of the integral format specifiers can have a third modifier after width
 457 and precision that specifies the base of the conversion from 2 to 64. In this
 458 case, the \fB#\fR modifier causes \fIbase\fR\fB#\fR to be prepended to the
 459 value.
 460 .RE
 461 .RS +4
 462 .TP
 463 .ie t \(bu
 464 .el o
 465 The \fB#\fR modifier can be used with the \fBd\fR specifier when no base is
 466 specified to cause the output to be written in units of 1000 with a suffix of
 467 one of \fBk M G T P E\fR.
 468 .RE
 469 .RS +4
 470 .TP
 471 .ie t \(bu
 472 .el o
 473 The \fB#\fR modifier can be used with the \fBi\fR specifier to cause the output
 474 to be written in units of \fB1024\fR with a suffix of one of \fBKi Mi Gi Ti Pi
 475 Ei\fR.
 476 .RE
 477 .sp
 478 .LP
 479 If there are more \fIstring\fR operands than format specifiers, the format
 480 string is reprocessed from the beginning. If there are fewer \fIstring\fR
 481 operands than format specifiers, then \fIstring\fR specifiers are treated as if
 482 empty strings were supplied, numeric conversions are treated as if \fB0\fR was
 483 supplied, and time conversions are treated as if \fBnow\fR was supplied.
 484 .sp
 485 .LP
 486 When there are more argument operands than format specifiers, and the
 487 format includes \fIn\fR\fB$\fR position indicators, then the format is
 488 reprocessed from the beginning as above, but with the argument list starting
 489 from the next argument after the highest \fIn\fRth argument previously
 490 encountered.
 491 .sp
 492 .LP
 493 \fB/usr/bin/printf\fR is equivalent to \fBksh93\fR's \fBprintf\fR built-in and
 494 \fBprint -f\fR, which allows additional options to be specified.
 495 .SH USAGE
 496 .SS "/usr/bin/printf"
 497 .sp
 498 .LP
 499 The \fBprintf\fR utility, like the \fBprintf\fR(3C) function on which it is
 500 based, makes no special provision for dealing with multi-byte characters when
 501 using the \fB%c\fR conversion specification. Applications should be extremely
 502 cautious using either of these features when there are multi-byte characters in
 503 the character set.
 504 .sp
 505 .LP
 506 The \fB%b\fR conversion specification is not part of the ISO C standard; it has
 507 been added here as a portable way to process backslash escapes expanded in
 508 string operands as provided by the \fBecho\fR utility. See also the USAGE
 509 section of the \fBecho\fR(1) manual page for ways to use \fBprintf\fR as a
 510 replacement for all of the traditional versions of the \fBecho\fR utility.
 511 .sp
 512 .LP
 513 If an argument cannot be parsed correctly for the corresponding conversion
 514 specification, the \fBprintf\fR utility reports an error. Thus, overflow and
 515 extraneous characters at the end of an argument being used for a numeric
 516 conversion are to be reported as errors.
 517 .sp
 518 .LP
 519 It is not considered an error if an argument operand is not completely used for
 520 a \fBc\fR or \fBs\fR conversion or if a string operand's first or second
 521 character is used to get the numeric value of a character.
 522 .SH EXAMPLES
 523 .SS "/usr/bin/printf"
 524 .LP
 525 \fBExample 1 \fRPrinting a Series of Prompts
 526 .sp
 527 .LP
 528 The following example alerts the user, then prints and reads a series of
 529 prompts:
 530 
 531 .sp
 532 .in +2
 533 .nf
 534 example% \fBprintf "\eaPlease fill in the following: \enName: "
 535 read name
 536 printf "Phone number: "
 537 read phone\fR
 538 .fi
 539 .in -2
 540 .sp
 541 
 542 .LP
 543 \fBExample 2 \fRPrinting a Table of Calculations
 544 .sp
 545 .LP
 546 The following example prints a table of calculations. It reads out a list of
 547 right and wrong answers from a file, calculates the percentage correctly, and
 548 prints them out. The numbers are right-justified and separated by a single tab
 549 character. The percentage is written to one decimal place of accuracy:
 550 
 551 .sp
 552 .in +2
 553 .nf
 554 example% \fBwhile read right wrong ; do
 555    percent=$(echo "scale=1;($right*100)/($right+$wrong)" | bc)
 556    printf "%2d right\et%2d wrong\et(%s%%)\en" \e
 557            $right $wrong $percent
 558 done < database_file\fR
 559 .fi
 560 .in -2
 561 .sp
 562 
 563 .LP
 564 \fBExample 3 \fRPrinting number strings
 565 .sp
 566 .LP
 567 The command:
 568 
 569 .sp
 570 .in +2
 571 .nf
 572 example% \fBprintf "%5d%4d\en" 1 21 321 4321 54321\fR
 573 .fi
 574 .in -2
 575 .sp
 576 
 577 .sp
 578 .LP
 579 produces:
 580 
 581 .sp
 582 .in +2
 583 .nf
 584     1  21
 585   3214321
 586 54321   0
 587 .fi
 588 .in -2
 589 .sp
 590 
 591 .sp
 592 .LP
 593 The \fIformat\fR operand is used three times to print all of the given strings
 594 and that a \fB0\fR was supplied by \fBprintf\fR to satisfy the last \fB%4d\fR
 595 conversion specification.
 596 
 597 .LP
 598 \fBExample 4 \fRTabulating Conversion Errors
 599 .sp
 600 .LP
 601 The following example tabulates conversion errors.
 602 
 603 .sp
 604 .LP
 605 The \fBprintf\fR utility tells the user when conversion errors are detected
 606 while producing numeric output. These results would be expected on an
 607 implementation with 32-bit twos-complement integers when \fB%d\fR is specified
 608 as the \fIformat\fR operand:
 609 
 610 .sp
 611 
 612 .sp
 613 .TS
 614 box;
 615 c c c
 616 l l l .
 617 Arguments       Standard        Diagnostic
 618 5a      5       printf: 5a not completely converted
 619 9999999999      2147483647      printf: 9999999999: Results too large
 620 -9999999999     -2147483648     printf: -9999999999: Results too large
 621 ABC     0       printf: ABC expected numeric value
 622 .TE
 623 
 624 .sp
 625 .LP
 626 The value shown on standard output is what would be expected as the return
 627 value from the function \fBstrtol\fR(3C). A similar correspondence exists
 628 between \fB%u\fR and \fBstrtoul\fR(3C), and \fB%e\fR, \fB%f\fR and \fB%g\fR and
 629 \fBstrtod\fR(3C).
 630 
 631 .LP
 632 \fBExample 5 \fRPrinting Output for a Specific Locale
 633 .sp
 634 .LP
 635 The following example prints output for a specific locale. In a locale using
 636 the ISO/IEC 646:1991 standard as the underlying codeset, the command:
 637 
 638 .sp
 639 .in +2
 640 .nf
 641 example% \fBprintf "%d\en" 3 +3 -3 \e'3 \e"+3 "'-3"\fR
 642 .fi
 643 .in -2
 644 .sp
 645 
 646 .sp
 647 .LP
 648 produces:
 649 
 650 .sp
 651 
 652 .sp
 653 .TS
 654 box;
 655 l l
 656 l l .
 657 \fB3\fR Numeric value of constant 3
 658 \fB3\fR Numeric value of constant 3
 659 \fB\(mi3\fR     Numeric value of constant \(mi3
 660 \fB51\fR        T{
 661 Numeric value of the character `3' in the ISO/IEC 646:1991 standard codeset
 662 T}
 663 \fB43\fR        T{
 664 Numeric value of the character `+' in the ISO/IEC 646:1991 standard codeset
 665 T}
 666 \fB45\fR        T{
 667 Numeric value of the character `\(mi' in the SO/IEC 646:1991 standard codeset
 668 T}
 669 .TE
 670 
 671 .sp
 672 .LP
 673 In a locale with multi-byte characters, the value of a character is intended to
 674 be the value of the equivalent of the \fBwchar_t\fR representation of the
 675 character.
 676 
 677 .sp
 678 .LP
 679 If an argument operand cannot be completely converted into an internal value
 680 appropriate to the corresponding conversion specification, a diagnostic message
 681 is written to standard error and the utility does exit with a zero exit status,
 682 but continues processing any remaining operands and writes the value
 683 accumulated at the time the error was detected to standard output.
 684 
 685 .LP
 686 \fBExample 6 \fRAlternative floating point representation 1
 687 .sp
 688 .LP
 689 The \fBprintf\fR utility supports an alternative floating point representation
 690 (see \fBprintf\fR(3C) entry for the "\fB%a\fR"/"\fB%A\fR"), which allows the
 691 output of floating-point values in a format that avoids the usual base16 to
 692 base10 rounding errors.
 693 
 694 .sp
 695 .in +2
 696 .nf
 697 example% printf "%a\en" 2 3.1 NaN
 698 .fi
 699 .in -2
 700 .sp
 701 
 702 .sp
 703 .LP
 704 produces:
 705 
 706 .sp
 707 .in +2
 708 .nf
 709 0x1.0000000000000000000000000000p+01
 710 0x1.8ccccccccccccccccccccccccccdp+01
 711 nan
 712 .fi
 713 .in -2
 714 .sp
 715 
 716 .LP
 717 \fBExample 7 \fRAlternative floating point representation 2
 718 .sp
 719 .LP
 720 The following example shows two different representations of the same
 721 floating-point value.
 722 
 723 .sp
 724 .in +2
 725 .nf
 726 example% x=2 ; printf "%f == %a\en" x x
 727 .fi
 728 .in -2
 729 .sp
 730 
 731 .sp
 732 .LP
 733 produces:
 734 
 735 .sp
 736 .in +2
 737 .nf
 738 2.000000 == 0x1.0000000000000000000000000000p+01
 739 .fi
 740 .in -2
 741 .sp
 742 
 743 .LP
 744 \fBExample 8 \fROutput of unicode values
 745 .sp
 746 .LP
 747 The following command will print the EURO unicode symbol (code-point 0x20ac).
 748 
 749 .sp
 750 .in +2
 751 .nf
 752 example% LC_ALL=en_US.UTF-8 printf "\u[20ac]\en"
 753 .fi
 754 .in -2
 755 .sp
 756 
 757 .sp
 758 .LP
 759 produces:
 760 
 761 .sp
 762 .in +2
 763 .nf
 764 <euro>
 765 .fi
 766 .in -2
 767 .sp
 768 
 769 .sp
 770 .LP
 771 where "<euro>" represents the EURO currency symbol character.
 772 
 773 .LP
 774 \fBExample 9 \fRConvert unicode character to unicode code-point value
 775 .sp
 776 .LP
 777 The following command will print the hexadecimal value of a given character.
 778 
 779 .sp
 780 .in +2
 781 .nf
 782 example% export LC_ALL=en_US.UTF-8
 783 example% printf "%x\en" "'<euro>"
 784 .fi
 785 .in -2
 786 .sp
 787 
 788 .sp
 789 .LP
 790 where "<euro>" represents the EURO currency symbol character (code-point
 791 0x20ac).
 792 
 793 .sp
 794 .LP
 795 produces:
 796 
 797 .sp
 798 .in +2
 799 .nf
 800 20ac
 801 .fi
 802 .in -2
 803 .sp
 804 
 805 .LP
 806 \fBExample 10 \fRPrint the numeric value of an ASCII character
 807 .sp
 808 .in +2
 809 .nf
 810 example% printf "%d\en" "'A"
 811 .fi
 812 .in -2
 813 .sp
 814 
 815 .sp
 816 .LP
 817 produces:
 818 
 819 .sp
 820 .in +2
 821 .nf
 822 65
 823 .fi
 824 .in -2
 825 .sp
 826 
 827 .LP
 828 \fBExample 11 \fRPrint the language-independent date and time format
 829 .sp
 830 .LP
 831 To print the language-independent date and time format, the following statement
 832 could be used:
 833 
 834 .sp
 835 .in +2
 836 .nf
 837 example% printf "format" weekday month day hour min
 838 .fi
 839 .in -2
 840 .sp
 841 
 842 .sp
 843 .LP
 844 For example,
 845 
 846 .sp
 847 .in +2
 848 .nf
 849 $ printf format "Sunday" "July" 3 10 2
 850 .fi
 851 .in -2
 852 .sp
 853 
 854 .sp
 855 .LP
 856 For American usage, format could be the string:
 857 
 858 .sp
 859 .in +2
 860 .nf
 861 "%s, %s %d, %d:%.2d\en"
 862 .fi
 863 .in -2
 864 .sp
 865 
 866 .sp
 867 .LP
 868 producing the message:
 869 
 870 .sp
 871 .in +2
 872 .nf
 873 Sunday, July 3, 10:02
 874 .fi
 875 .in -2
 876 .sp
 877 
 878 .sp
 879 .LP
 880 Whereas for EU usage, format could be the string:
 881 
 882 .sp
 883 .in +2
 884 .nf
 885 "%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
 886 .fi
 887 .in -2
 888 .sp
 889 
 890 .sp
 891 .LP
 892 Note that the '$' characters must be properly escaped, such as
 893 
 894 .sp
 895 .in +2
 896 .nf
 897 "%1\e$s, %3\e$d. %2\e$s, %4\e$d:%5\e$.2d\en" in this case
 898 .fi
 899 .in -2
 900 .sp
 901 
 902 .sp
 903 .LP
 904 producing the message:
 905 
 906 .sp
 907 .in +2
 908 .nf
 909 Sunday, 3. July, 10:02
 910 .fi
 911 .in -2
 912 .sp
 913 
 914 .SH ENVIRONMENT VARIABLES
 915 .sp
 916 .LP
 917 See \fBenviron\fR(5) for descriptions of the following environment variables
 918 that affect the execution of \fBprintf\fR: \fBLANG\fR, \fBLC_ALL\fR,
 919 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, \fBLC_NUMERIC\fR, and \fBNLSPATH\fR.
 920 .SH EXIT STATUS
 921 .sp
 922 .LP
 923 The following exit values are returned:
 924 .sp
 925 .ne 2
 926 .na
 927 \fB\fB0\fR\fR
 928 .ad
 929 .RS 6n
 930 Successful completion.
 931 .RE
 932 
 933 .sp
 934 .ne 2
 935 .na
 936 \fB\fB>0\fR\fR
 937 .ad
 938 .RS 6n
 939 An error occurred.
 940 .RE
 941 
 942 .SH ATTRIBUTES
 943 .sp
 944 .LP
 945 See \fBattributes\fR(5) for descriptions of the following attributes:
 946 .SS "/usr/bin/printf"
 947 .sp
 948 
 949 .sp
 950 .TS
 951 box;
 952 c | c
 953 l | l .
 954 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 955 _
 956 CSI     Enabled
 957 _
 958 Interface Stability     Committed
 959 _
 960 Standard        See \fBstandards\fR(5).
 961 .TE
 962 
 963 .SS "ksh93"
 964 .sp
 965 
 966 .sp
 967 .TS
 968 box;
 969 c | c
 970 l | l .
 971 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 972 _
 973 Interface Stability     Uncommitted
 974 .TE
 975 
 976 .SH SEE ALSO
 977 .sp
 978 .LP
 979 \fBawk\fR(1), \fBbc\fR(1), \fBdate\fR(1), \fBecho\fR(1), \fBksh93\fR(1),
 980 \fBprintf\fR(3C), \fBstrtod\fR(3C), \fBstrtol\fR(3C), \fBstrtoul\fR(3C),
 981 \fBattributes\fR(5), \fBenviron\fR(5), \fBformats\fR(5), \fBstandards\fR(5)
 982 .SH NOTES
 983 .sp
 984 .LP
 985 Using format specifiers (characters following '%') which are not listed in the
 986 \fBprintf\fR(3C) or this manual page will result in undefined behavior.
 987 .sp
 988 .LP
 989 Using escape sequences (the character following a backslash ('\e')) which are
 990 not listed in the \fBprintf\fR(3C) or this manual page will result in undefined
 991 behavior.
 992 .sp
 993 .LP
 994 Floating-point values follow C99, XPG6 and IEEE 754 standard behavior and can
 995 handle values the same way as the platform's |\fBlong double\fR| datatype.
 996 .sp
 997 .LP
 998 Floating-point values handle the sign separately which allows signs for values
 999 like NaN (for example, -nan), Infinite (for example, -inf) and zero (for
1000 example, -0.0).