1 PRINTF(3C) Standard C Library Functions PRINTF(3C)
2
3
4
5 NAME
6 printf, fprintf, sprintf, snprintf, asprintf - print formatted output
7
8 SYNOPSIS
9 #include <stdio.h>
10
11 int printf(const char *restrict format,
12 /* args*/ ...);
13
14
15 int fprintf(FILE *restrict stream, const char *restrict format,
16 /* args*/ ...);
17
18
19 int sprintf(char *restrict s, const char *restrict format,
20 /* args*/ ...);
21
22
23 int snprintf(char *restrict s, size_t n,
24 const char *restrict format, /* args*/ ...);
25
26
27 int asprintf(char ** ret, const char *restrict format,
28 /* args*/ ...);
29
30
31 DESCRIPTION
32 The printf() function places output on the standard output stream
33 stdout.
34
35
36 The fprintf() function places output on on the named output stream
37 stream.
38
39
40 The sprintf() function places output, followed by the null byte (\0),
41 in consecutive bytes starting at s; it is the user's responsibility to
42 ensure that enough storage is available.
43
44
45 The snprintf() function is identical to sprintf() with the addition of
46 the argument n, which specifies the size of the buffer referred to by
47 s. If n is 0, nothing is written and s can be a null pointer.
48 Otherwise, output bytes beyond the n-1st are discarded instead of being
49 written to the array and a null byte is written at the end of the bytes
50 actually written into the array.
51
52
53 The asprintf() function is the same as the sprintf() function except
54 that it returns, in the ret argument, a pointer to a buffer
55 sufficiently large to hold the output string. This pointer should be
56 passed to free(3C) to release the allocated storage when it is no
57 longer needed. If sufficient space cannot be allocated, the asprintf()
58 function returns -1 and sets ret to be a NULL pointer.
59
60
61 Each of these functions converts, formats, and prints its arguments
62 under control of the format. The format is a character string,
63 beginning and ending in its initial shift state, if any. The format is
64 composed of zero or more directives: ordinary characters, which are
65 simply copied to the output stream and conversion specifications, each
66 of which results in the fetching of zero or more arguments. The results
67 are undefined if there are insufficient arguments for the format. If
68 the format is exhausted while arguments remain, the excess arguments
69 are evaluated but are otherwise ignored.
70
71
72 Conversions can be applied to the nth argument after the format in the
73 argument list, rather than to the next unused argument. In this case,
74 the conversion specifier % (see below) is replaced by the sequence %n$,
75 where n is a decimal integer in the range [1, NL_ARGMAX], giving the
76 position of the argument in the argument list. This feature provides
77 for the definition of format strings that select arguments in an order
78 appropriate to specific languages (see the EXAMPLES section).
79
80
81 In format strings containing the %n$ form of conversion specifications,
82 numbered arguments in the argument list can be referenced from the
83 format string as many times as required.
84
85
86 In format strings containing the % form of conversion specifications,
87 each argument in the argument list is used exactly once.
88
89
90 All forms of the printf() functions allow for the insertion of a
91 language-dependent radix character in the output string. The radix
92 character is defined by the program's locale (category LC_NUMERIC). In
93 the POSIX locale, or in a locale where the radix character is not
94 defined, the radix character defaults to a period (.).
95
96 Conversion Specifications
97 Each conversion specification is introduced by the % character or by
98 the character sequence %n$, after which the following appear in
99 sequence:
100
101 o An optional field, consisting of a decimal digit string
102 followed by a $, specifying the next argument to be
103 converted. If this field is not provided, the args following
104 the last argument converted will be used.
105
106 o Zero or more flags (in any order), which modify the meaning
107 of the conversion specification.
108
109 o An optional minimum field width. If the converted value has
110 fewer bytes than the field width, it will be padded with
111 spaces by default on the left; it will be padded on the
112 right, if the left-adjustment flag (-), described below, is
113 given to the field width. The field width takes the form of
114 an asterisk (*), described below, or a decimal integer.
115
116 If the conversion specifier is s, a standard-conforming
117 application (see standards(5)) interprets the field width as
118 the minimum number of bytes to be printed; an application
119 that is not standard-conforming interprets the field width
120 as the minimum number of columns of screen display. For an
121 application that is not standard-conforming, %10s means if
122 the converted value has a screen width of 7 columns, 3
123 spaces would be padded on the right.
124
125 If the format is %ws, then the field width should be
126 interpreted as the minimum number of columns of screen
127 display.
128
129 o An optional precision that gives the minimum number of
130 digits to appear for the d, i, o, u, x, and X conversions
131 (the field is padded with leading zeros); the number of
132 digits to appear after the radix character for the a, A, e,
133 E, f, and F conversions, the maximum number of significant
134 digits for the g and G conversions; or the maximum number of
135 bytes to be printed from a string in s and S conversions.
136 The precision takes the form of a period (.) followed either
137 by an asterisk (*), described below, or an optional decimal
138 digit string, where a null digit string is treated as 0. If
139 a precision appears with any other conversion specifier, the
140 behavior is undefined.
141
142 If the conversion specifier is s or S, a standard-conforming
143 application (see standards(5)) interprets the precision as
144 the maximum number of bytes to be written; an application
145 that is not standard-conforming interprets the precision as
146 the maximum number of columns of screen display. For an
147 application that is not standard-conforming, %.5s would
148 print only the portion of the string that would display in 5
149 screen columns. Only complete characters are written.
150
151 For %ws, the precision should be interpreted as the maximum
152 number of columns of screen display. The precision takes the
153 form of a period (.) followed by a decimal digit string; a
154 null digit string is treated as zero. Padding specified by
155 the precision overrides the padding specified by the field
156 width.
157
158 o An optional length modifier that specified the size of the
159 argument.
160
161 o A conversion specifier that indicates the type of conversion
162 to be applied.
163
164
165 A field width, or precision, or both can be indicated by an asterisk
166 (*) . In this case, an argument of type int supplies the field width or
167 precision. Arguments specifying field width, or precision, or both must
168 appear in that order before the argument, if any, to be converted. A
169 negative field width is taken as a - flag followed by a positive field
170 width. A negative precision is taken as if the precision were omitted.
171 In format strings containing the %n$ form of a conversion
172 specification, a field width or precision may be indicated by the
173 sequence *m$, where m is a decimal integer in the range [1, NL_ARGMAX]
174 giving the position in the argument list (after the format argument) of
175 an integer argument containing the field width or precision, for
176 example:
177
178 printf("%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec);
179
180
181
182 The format can contain either numbered argument specifications (that
183 is, %n$ and *m$), or unnumbered argument specifications (that is, % and
184 *), but normally not both. The only exception to this is that %% can be
185 mixed with the %n$ form. The results of mixing numbered and unnumbered
186 argument specifications in a format string are undefined. When numbered
187 argument specifications are used, specifying the Nth argument requires
188 that all the leading arguments, from the first to the (N-1)th, are
189 specified in the format string.
190
191 Flag Characters
192 The flag characters and their meanings are:
193
194 '
195 The integer portion of the result of a decimal conversion (%i,
196 %d, %u, %f, %F, %g, or %G) will be formatted with thousands'
197 grouping characters. For other conversions the behavior is
198 undefined. The non-monetary grouping character is used.
199
200
201 -
202 The result of the conversion will be left-justified within the
203 field. The conversion will be right-justified if this flag is
204 not specified.
205
206
207 +
208 The result of a signed conversion will always begin with a
209 sign (+ or -). The conversion will begin with a sign only when
210 a negative value is converted if this flag is not specified.
211
212
213 space
214 If the first character of a signed conversion is not a sign or
215 if a signed conversion results in no characters, a space will
216 be placed before the result. This means that if the space and
217 + flags both appear, the space flag will be ignored.
218
219
220 #
221 The value is to be converted to an alternate form. For c, d,
222 i, s, and u conversions, the flag has no effect. For an o
223 conversion, it increases the precision (if necessary) to force
224 the first digit of the result to be a zero. For x or X
225 conversion, a non-zero result will have 0x (or 0X) prepended
226 to it. For a, A, e, E, f, F, g, and G conversions, the result
227 will always contain a radix character, even if no digits
228 follow the radix character. Without this flag, the radix
229 character appears in the result of these conversions only if a
230 digit follows it. For g and G conversions, trailing zeros will
231 not be removed from the result as they normally are.
232
233
234 0
235 For d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversions,
236 leading zeros (following any indication of sign or base) are
237 used to pad to the field width; no space padding is performed.
238 If the 0 and - flags both appear, the 0 flag will be ignored.
239 For d, i, o, u, x, and X conversions, if a precision is
240 specified, the 0 flag will be ignored. If the 0 and ' flags
241 both appear, the grouping characters are inserted before zero
242 padding. For other conversions, the behavior is undefined.
243
244
245 Length Modifiers
246 The length modifiers and their meanings are:
247
248 hh
249 Specifies that a following d, i, o, u, x, or X
250 conversion specifier applies to a signed char or
251 unsigned char argument (the argument will have been
252 promoted according to the integer promotions, but its
253 value will be converted to signed char or unsigned char
254 before printing); or that a following n conversion
255 specifier applies to a pointer to a signed char
256 argument.
257
258
259 h
260 Specifies that a following d, i, o, u, x, or X
261 conversion specifier applies to a short or unsigned
262 short argument (the argument will have been promoted
263 according to the integer promotions, but its value will
264 be converted to short or unsigned short before
265 printing); or that a following n conversion specifier
266 applies to a pointer to a short argument.
267
268
269 l (ell)
270 Specifies that a following d, i, o, u, x, or X
271 conversion specifier applies to a long or unsigned long
272 argument; that a following n conversion specifier
273 applies to a pointer to a long argument; that a
274 following c conversion specifier applies to a wint_t
275 argument; that a following s conversion specifier
276 applies to a pointer to a wchar_t argument; or has no
277 effect on a following a, A, e, E, f, F, g, or G
278 conversion specifier.
279
280
281 ll (ell-ell)
282 Specifies that a following d, i, o, u, x, or X
283 conversion specifier applies to a long long or unsigned
284 long long argument; or that a following n conversion
285 specifier applies to a pointer to a long long argument.
286
287
288 j
289 Specifies that a following d, i, o, u, x, or X
290 conversion specifier applies to an intmax_t or
291 uintmax_t argument; or that a following n conversion
292 specifier applies to a pointer to an intmax_t argument.
293 See NOTES.
294
295
296 z
297 Specifies that a following d, i, o, u, x, or X
298 conversion specifier applies to a size_t or the
299 corresponding signed integer type argument; or that a
300 following n conversion specifier applies to a pointer
301 to a signed integer type corresponding to size_t
302 argument.
303
304
305 t
306 Specifies that a following d, i, o, u, x, or X
307 conversion specifier applies to a ptrdiff_t or the
308 corresponding unsigned type argument; or that a
309 following n conversion specifier applies to a pointer
310 to a ptrdiff_t argument.
311
312
313 L
314 Specifies that a following a, A, e, E, f, F, g, or G
315 conversion specifier applies to a long double argument.
316
317
318
319 If a length modifier appears with any conversion specifier other than
320 as specified above, the behavior is undefined.
321
322 Conversion Specifiers
323 Each conversion specifier results in fetching zero or more arguments.
324 The results are undefined if there are insufficient arguments for the
325 format. If the format is exhausted while arguments remain, the excess
326 arguments are ignored.
327
328
329 The conversion specifiers and their meanings are:
330
331 d, i
332 The int argument is converted to a signed decimal in the style
333 [-]dddd. The precision specifies the minimum number of digits
334 to appear; if the value being converted can be represented in
335 fewer digits, it will be expanded with leading zeros. The
336 default precision is 1. The result of converting 0 with an
337 explicit precision of 0 is no characters.
338
339
340 o
341 The unsigned int argument is converted to unsigned octal format
342 in the style dddd. The precision specifies the minimum number
343 of digits to appear; if the value being converted can be
344 represented in fewer digits, it will be expanded with leading
345 zeros. The default precision is 1. The result of converting 0
346 with an explicit precision of 0 is no characters.
347
348
349 u
350 The unsigned int argument is converted to unsigned decimal
351 format in the style dddd. The precision specifies the minimum
352 number of digits to appear; if the value being converted can be
353 represented in fewer digits, it will be expanded with leading
354 zeros. The default precision is 1. The result of converting 0
355 with an explicit precision of 0 is no characters.
356
357
358 x
359 The unsigned int argument is converted to unsigned hexadecimal
360 format in the style dddd; the letters abcdef are used. The
361 precision specifies the minimum number of digits to appear; if
362 the value being converted can be represented in fewer digits,
363 it will be expanded with leading zeros. The default precision
364 is 1. The result of converting 0 with an explicit precision of
365 0 is no characters.
366
367
368 X
369 Behaves the same as the x conversion specifier except that
370 letters ABCDEF are used instead of abcdef.
371
372
373 f, F
374 The double argument is converted to decimal notation in the
375 style [-]ddd.ddd, where the number of digits after the radix
376 character (see setlocale(3C)) is equal to the precision
377 specification. If the precision is missing it is taken as 6; if
378 the precision is explicitly 0 and the # flag is not specified,
379 no radix character appears. If a radix character appears, at
380 least 1 digit appears before it. The converted value is rounded
381 to fit the specified output format according to the prevailing
382 floating point rounding direction mode. If the conversion is
383 not exact, an inexact exception is raised.
384
385 For the f specifier, a double argument representing an infinity
386 or NaN is converted in the style of the e conversion specifier,
387 except that for an infinite argument, "infinity" or "Infinity"
388 is printed when the precision is at least 8 and "inf" or "Inf"
389 is printed otherwise.
390
391 For the F specifier, a double argument representing an infinity
392 or NaN is converted in the SUSv3 style of the E conversion
393 specifier, except that for an infinite argument, "INFINITY" is
394 printed when the precision is at least 8 and or "INF" is
395 printed otherwise.
396
397
398 e, E
399 The double argument is converted to the style [-]d.ddde+-dd,
400 where there is one digit before the radix character (which is
401 non-zero if the argument is non-zero) and the number of digits
402 after it is equal to the precision. When the precision is
403 missing it is taken as 6; if the precision is 0 and the # flag
404 is not specified, no radix character appears. The E conversion
405 specifier will produce a number with E instead of e introducing
406 the exponent. The exponent always contains at least two digits.
407 The converted value is rounded to fit the specified output
408 format according to the prevailing floating point rounding
409 direction mode. If the conversion is not exact, an inexact
410 exception is raised.
411
412 Infinity and NaN values are handled in one of the following
413 ways:
414
415 SUSv3
416 For the e specifier, a double argument representing
417 an infinity is printed as "[-]infinity", when the
418 precision for the conversion is at least 7 and as
419 "[-]inf" otherwise. A double argument representing a
420 NaN is printed as "[-]nan". For the E specifier,
421 "INF", "INFINITY", and "NAN" are printed instead of
422 "inf", "infinity", and "nan", respectively. Printing
423 of the sign follows the rules described above.
424
425
426 Default
427 A double argument representing an infinity is
428 printed as "[-]Infinity", when the precision for the
429 conversion is at least 7 and as "[-]Inf" otherwise.
430 A double argument representing a NaN is printed as
431 "[-]NaN". Printing of the sign follows the rules
432 described above.
433
434
435
436 g, G
437 The double argument is printed in style f or e (or in style E
438 in the case of a G conversion specifier), with the precision
439 specifying the number of significant digits. If an explicit
440 precision is 0, it is taken as 1. The style used depends on the
441 value converted: style e (or E) will be used only if the
442 exponent resulting from the conversion is less than -4 or
443 greater than or equal to the precision. Trailing zeros are
444 removed from the fractional part of the result. A radix
445 character appears only if it is followed by a digit.
446
447 A double argument representing an infinity or NaN is converted
448 in the style of the e or E conversion specifier, except that
449 for an infinite argument, "infinity", "INFINITY", or "Infinity"
450 is printed when the precision is at least 8 and "inf", "INF",
451 or "Inf" is printed otherwise.
452
453
454 a, A
455 A double argument representing a floating-point number is
456 converted in the style "[-]0xh.hhhhp+-d", where the single
457 hexadecimal digit preceding the radix point is 0 if the value
458 converted is zero and 1 otherwise and the number of hexadecimal
459 digits after it is equal to the precision; if the precision is
460 missing, the number of digits printed after the radix point is
461 13 for the conversion of a double value, 16 for the conversion
462 of a long double value on x86, and 28 for the conversion of a
463 long double value on SPARC; if the precision is zero and the
464 '#' flag is not specified, no decimal-point character will
465 appear. The letters "abcdef" are used for a conversion and the
466 letters "ABCDEF" for A conversion. The A conversion specifier
467 produces a number with 'X' and 'P' instead of 'x' and 'p'. The
468 exponent will always contain at least one digit, and only as
469 many more digits as necessary to represent the decimal exponent
470 of 2. If the value is zero, the exponent is zero.
471
472 The converted value is rounded to fit the specified output
473 format according to the prevailing floating point rounding
474 direction mode. If the conversion is not exact, an inexact
475 exception is raised.
476
477 A double argument representing an infinity or NaN is converted
478 in the SUSv3 style of an e or E conversion specifier.
479
480
481 c
482 The int argument is converted to an unsigned char, and the
483 resulting byte is printed.
484
485 If an l (ell) qualifier is present, the wint_t argument is
486 converted as if by an ls conversion specification with no
487 precision and an argument that points to a two-element array of
488 type wchar_t, the first element of which contains the wint_t
489 argument to the ls conversion specification and the second
490 element contains a null wide-character.
491
492
493 C
494 Same as lc.
495
496
497 wc
498 The int argument is converted to a wide character (wchar_t),
499 and the resulting wide character is printed.
500
501
502 s
503 The argument must be a pointer to an array of char. Bytes from
504 the array are written up to (but not including) any terminating
505 null byte. If a precision is specified, a standard-conforming
506 application (see standards(5)) will write only the number of
507 bytes specified by precision; an application that is not
508 standard-conforming will write only the portion of the string
509 that will display in the number of columns of screen display
510 specified by precision. If the precision is not specified, it
511 is taken to be infinite, so all bytes up to the first null byte
512 are printed. An argument with a null value will yield undefined
513 results.
514
515 If an l (ell) qualifier is present, the argument must be a
516 pointer to an array of type wchar_t. Wide-characters from the
517 array are converted to characters (each as if by a call to the
518 wcrtomb(3C) function, with the conversion state described by an
519 mbstate_t object initialized to zero before the first wide-
520 character is converted) up to and including a terminating null
521 wide-character. The resulting characters are written up to (but
522 not including) the terminating null character (byte). If no
523 precision is specified, the array must contain a null wide-
524 character. If a precision is specified, no more than that many
525 characters (bytes) are written (including shift sequences, if
526 any), and the array must contain a null wide-character if, to
527 equal the character sequence length given by the precision, the
528 function would need to access a wide-character one past the end
529 of the array. In no case is a partial character written.
530
531
532 S
533 Same as ls.
534
535
536 ws
537 The argument must be a pointer to an array of wchar_t. Bytes
538 from the array are written up to (but not including) any
539 terminating null character. If the precision is specified, only
540 that portion of the wide-character array that will display in
541 the number of columns of screen display specified by precision
542 will be written. If the precision is not specified, it is taken
543 to be infinite, so all wide characters up to the first null
544 character are printed. An argument with a null value will yield
545 undefined results.
546
547
548 p
549 The argument must be a pointer to void. The value of the
550 pointer is converted to a set of sequences of printable
551 characters, which should be the same as the set of sequences
552 that are matched by the %p conversion of the scanf(3C)
553 function.
554
555
556 n
557 The argument must be a pointer to an integer into which is
558 written the number of bytes written to the output standard I/O
559 stream so far by this call to one of the printf() functions. No
560 argument is converted.
561
562
563 %
564 Print a %; no argument is converted. The entire conversion
565 specification must be %%.
566
567
568
569 If a conversion specification does not match one of the above forms,
570 the behavior is undefined.
571
572
573 In no case does a non-existent or small field width cause truncation of
574 a field; if the result of a conversion is wider than the field width,
575 the field is simply expanded to contain the conversion result.
576 Characters generated by printf() and fprintf() are printed as if the
577 putc(3C) function had been called.
578
579
580 The st_ctime and st_mtime fields of the file will be marked for update
581 between the call to a successful execution of printf() or fprintf() and
582 the next successful completion of a call to fflush(3C) or fclose(3C) on
583 the same stream or a call to exit(3C) or abort(3C).
584
585 RETURN VALUES
586 The printf(), fprintf(), sprintf(), and asprintf() functions return the
587 number of bytes transmitted (excluding the terminating null byte in the
588 case of sprintf() and asprintf()).
589
590
591 The snprintf() function returns the number of bytes that would have
592 been written to s if n had been sufficiently large (excluding the
593 terminating null byte.) If the value of n is 0 on a call to snprintf(),
594 s can be a null pointer and the number of bytes that would have been
595 written if n had been sufficiently large (excluding the terminating
596 null byte) is returned.
597
598
599 Each function returns a negative value if an output error was
600 encountered.
601
602 ERRORS
603 For the conditions under which printf() and fprintf() will fail and may
604 fail, refer to fputc(3C) or fputwc(3C).
605
606
607 The snprintf() function will fail if:
608
609 EOVERFLOW
610 The value of n is greater than INT_MAX or the number of
611 bytes needed to hold the output excluding the terminating
612 null is greater than INT_MAX.
613
614
615
616 The printf(), fprintf(), sprintf(), and snprintf() functions may fail
617 if:
618
619 EILSEQ
620 A wide-character code that does not correspond to a valid
621 character has been detected.
622
623
624 EINVAL
625 There are insufficient arguments.
626
627
628
629 The printf(), fprintf(), and asprintf() functions may fail due to an
630 underlying malloc(3C) failure if:
631
632 EAGAIN
633 Storage space is temporarily unavailable.
634
635
636 ENOMEM
637 Insufficient storage space is available.
638
639
640 USAGE
641 If the application calling the printf() functions has any objects of
642 type wint_t or wchar_t, it must also include the header <wchar.h> to
643 have these objects defined.
644
645 Escape Character Sequences
646 It is common to use the following escape sequences built into the C
647 language when entering format strings for the printf() functions, but
648 these sequences are processed by the C compiler, not by the printf()
649 function.
650
651 \a
652 Alert. Ring the bell.
653
654
655 \b
656 Backspace. Move the printing position to one character before
657 the current position, unless the current position is the start
658 of a line.
659
660
661 \f
662 Form feed. Move the printing position to the initial printing
663 position of the next logical page.
664
665
666 \n
667 Newline. Move the printing position to the start of the next
668 line.
669
670
671 \r
672 Carriage return. Move the printing position to the start of the
673 current line.
674
675
676 \t
677 Horizontal tab. Move the printing position to the next
678 implementation-defined horizontal tab position on the current
679 line.
680
681
682 \v
683 Vertical tab. Move the printing position to the start of the
684 next implementation-defined vertical tab position.
685
686
687
688 In addition, the C language supports character sequences of the form
689
690
691 \octal-number
692
693
694 and
695
696
697 \hex-number
698
699
700 which translates into the character represented by the octal or
701 hexadecimal number. For example, if ASCII representations are being
702 used, the letter 'a' may be written as '\141' and 'Z' as '\132'. This
703 syntax is most frequently used to represent the null character as '\0'.
704 This is exactly equivalent to the numeric constant zero (0). Note that
705 the octal number does not include the zero prefix as it would for a
706 normal octal constant. To specify a hexadecimal number, omit the zero
707 so that the prefix is an 'x' (uppercase 'X' is not allowed in this
708 context). Support for hexadecimal sequences is an ANSI extension. See
709 standards(5).
710
711 EXAMPLES
712 Example 1 To print the language-independent date and time format, the
713 following statement could be used:
714
715 printf (format, weekday, month, day, hour, min);
716
717
718
719 For American usage, format could be a pointer to the string:
720
721
722 "%s, %s %d, %d:%.2d\n"
723
724
725
726 producing the message:
727
728
729 Sunday, July 3, 10:02
730
731
732
733 whereas for German usage, format could be a pointer to the string:
734
735
736 "%1$s, %3$d. %2$s, %4$d:%5$.2d\n"
737
738
739
740 producing the message:
741
742
743 Sonntag, 3. Juli, 10:02
744
745
746 Example 2 To print a date and time in the form Sunday, July 3, 10:02,
747 where weekday and month are pointers to null-terminated strings:
748
749 printf("%s, %s %i, %d:%.2d", weekday, month, day, hour, min);
750
751
752 Example 3 To print pi to 5 decimal places:
753
754 printf("pi = %.5f", 4 * atan(1.0));
755
756
757 Default
758 Example 4 The following example applies only to applications that are
759 not standard-conforming. To print a list of names in columns which are
760 20 characters wide:
761
762 printf("%20s%20s%20s", lastname, firstname, middlename);
763
764
765 ATTRIBUTES
766 See attributes(5) for descriptions of the following attributes:
767
768
769
770
771 +--------------------+-----------------+
772 |ATTRIBUTE TYPE | ATTRIBUTE VALUE |
773 +--------------------+-----------------+
774 |CSI | Enabled |
775 +--------------------+-----------------+
776 |Interface Stability | Committed |
777 +--------------------+-----------------+
778 |MT-Level | See below. |
779 +--------------------+-----------------+
780 |Standard | See below. |
781 +--------------------+-----------------+
782
783
784 All of these functions can be used safely in multithreaded
785 applications, as long as setlocale(3C) is not being called to change
786 the locale. The sprintf() and snprintf() functions are Async-Signal-
787 Safe.
788
789
790 See standards(5) for the standards conformance of printf(), fprintf(),
791 sprintf(), and snprintf(). The asprintf() function is modeled on the
792 one that appears in the FreeBSD, NetBSD, and GNU C libraries.
793
794 SEE ALSO
795 exit(2), lseek(2), write(2), abort(3C), ecvt(3C), exit(3C), fclose(3C),
796 fflush(3C), fputwc(3C), free(3C), malloc(3C), putc(3C), scanf(3C),
797 setlocale(3C), stdio(3C), vprintf(3C), wcstombs(3C), wctomb(3C),
798 attributes(5), environ(5), standards(5)
799
800 NOTES
801 If the j length modifier is used, 32-bit applications that were
802 compiled using c89 on releases prior to Solaris 10 will experience
803 undefined behavior.
804
805
806 The snprintf() return value when n = 0 was changed in the Solaris 10
807 release. The change was based on the SUSv3 specification. The previous
808 behavior was based on the initial SUSv2 specification, where snprintf()
809 when n = 0 returns an unspecified value less than 1.
810
811
812
813 January 7, 2009 PRINTF(3C)
|
1 PRINTF(3C) Standard C Library Functions PRINTF(3C)
2
3 NAME
4 printf, fprintf, sprintf, snprintf, asprintf - print formatted output
5
6 LIBRARY
7 Standard C Library (libc, -lc)
8
9 SYNOPSIS
10 #include <stdio.h>
11
12 int
13 printf(const char *restrict format, /* args */ ...);
14
15 int
16 fprintf(FILE *restrict stream, const char *restrict format,
17 /* args */ ...);
18
19 int
20 sprintf(char *restrict s, const char *restrict format, /* args */ ...);
21
22 int
23 snprintf(char *restrict s, size_t n, const char *restrict format,
24 /* args */ ...);
25
26 int
27 asprintf(char **ret, const char *restrict format, /* args */ ...);
28
29 DESCRIPTION
30 The printf() function places output on the standard output stream stdout.
31
32 The fprintf() function places output on on the named output stream
33 stream.
34
35 The sprintf() function places output, followed by the null byte (`\0'),
36 in consecutive bytes starting at s; it is the user's responsibility to
37 ensure that enough storage is available.
38
39 The snprintf() function is identical to sprintf() with the addition of
40 the argument n, which specifies the size of the buffer referred to by s.
41 If n is 0, nothing is written and s can be a NULL pointer. Otherwise,
42 output bytes beyond the n-1st are discarded instead of being written to
43 the array and a null byte is written at the end of the bytes actually
44 written into the array.
45
46 The asprintf() function is the same as the sprintf() function except that
47 it returns, in the ret argument, a pointer to a buffer sufficiently large
48 to hold the output string. This pointer should be passed to free(3C) to
49 release the allocated storage when it is no longer needed. If sufficient
50 space cannot be allocated, the asprintf() function returns -1 and sets
51 ret to be a NULL pointer.
52
53 Each of these functions converts, formats, and prints its arguments under
54 control of the format. The format is a character string, beginning and
55 ending in its initial shift state, if any. The format is composed of
56 zero or more directives: ordinary characters, which are simply copied to
57 the output stream and conversion specifications, each of which results in
58 the fetching of zero or more arguments. The results are undefined if
59 there are insufficient arguments for the format. If the format is
60 exhausted while arguments remain, the excess arguments are evaluated but
61 are otherwise ignored.
62
63 Conversions can be applied to the nth argument after the format in the
64 argument list, rather than to the next unused argument. In this case,
65 the conversion specifier % (see below) is replaced by the sequence %n$,
66 where n is a decimal integer in the range [1, NL_ARGMAX], giving the
67 position of the argument in the argument list. This feature provides for
68 the definition of format strings that select arguments in an order
69 appropriate to specific languages (see the EXAMPLES section).
70
71 In format strings containing the %n$ form of conversion specifications,
72 numbered arguments in the argument list can be referenced from the format
73 string as many times as required.
74
75 In format strings containing the % form of conversion specifications,
76 each argument in the argument list is used exactly once.
77
78 All forms of the printf() functions allow for the insertion of a
79 language-dependent radix character in the output string. The radix
80 character is defined by the program's locale (category LC_NUMERIC). In
81 the POSIX locale, or in a locale where the radix character is not
82 defined, the radix character defaults to a period (.).
83
84 Conversion Specifications
85 Each conversion specification is introduced by the % character or by the
86 character sequence %n$, after which the following appear in sequence:
87
88 o An optional field, consisting of a decimal digit string followed by a
89 $, specifying the next argument to be converted. If this field is
90 not provided, the args following the last argument converted will be
91 used.
92
93 o Zero or more flags (in any order), which modify the meaning of the
94 conversion specification.
95
96 o An optional minimum field width. If the converted value has fewer
97 bytes than the field width, it will be padded with spaces by default
98 on the left; it will be padded on the right, if the left-adjustment
99 flag (-), described below, is given to the field width. The field
100 width takes the form of an asterisk (*), described below, or a
101 decimal integer.
102
103 If the conversion specifier is s, a standard-conforming application
104 (see standards(5)) interprets the field width as the minimum number
105 of bytes to be printed; an application that is not standard-
106 conforming interprets the field width as the minimum number of
107 columns of screen display. For an application that is not standard-
108 conforming, `%10s' means if the converted value has a screen width of
109 7 columns, 3 spaces would be padded on the right.
110
111 If the format is %ws, then the field width should be interpreted as
112 the minimum number of columns of screen display.
113
114 o An optional precision that gives the minimum number of digits to
115 appear for the d, i, o, u, x, and X conversions (the field is padded
116 with leading zeros); the number of digits to appear after the radix
117 character for the a, A, e, E, f, and F conversions, the maximum
118 number of significant digits for the g and G conversions; or the
119 maximum number of bytes to be printed from a string in s and S
120 conversions. The precision takes the form of a period (.) followed
121 either by an asterisk (*), described below, or an optional decimal
122 digit string, where a null digit string is treated as 0. If a
123 precision appears with any other conversion specifier, the behavior
124 is undefined.
125
126 If the conversion specifier is s or S, a standard-conforming
127 application (see standards(5)) interprets the precision as the
128 maximum number of bytes to be written; an application that is not
129 standard-conforming interprets the precision as the maximum number of
130 columns of screen display. For an application that is not standard-
131 conforming, `%.5s' would print only the portion of the string that
132 would display in 5 screen columns. Only complete characters are
133 written.
134
135 For %ws, the precision should be interpreted as the maximum number of
136 columns of screen display. The precision takes the form of a period
137 (.) followed by a decimal digit string; a null digit string is
138 treated as zero. Padding specified by the precision overrides the
139 padding specified by the field width.
140
141 o An optional length modifier that specified the size of the argument.
142
143 o A conversion specifier that indicates the type of conversion to be
144 applied.
145
146 A field width, or precision, or both can be indicated by an asterisk (*).
147 In this case, an argument of type int supplies the field width or
148 precision. Arguments specifying field width, or precision, or both must
149 appear in that order before the argument, if any, to be converted. A
150 negative field width is taken as a - flag followed by a positive field
151 width. A negative precision is taken as if the precision were omitted.
152 In format strings containing the %n$ form of a conversion specification,
153 a field width or precision may be indicated by the sequence *m$, where m
154 is a decimal integer in the range [1, NL_ARGMAX] giving the position in
155 the argument list (after the format argument) of an integer argument
156 containing the field width or precision, for example:
157
158 printf("%1$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec);
159
160 The format can contain either numbered argument specifications (that is,
161 %n$ and *m$), or unnumbered argument specifications (that is, % and *),
162 but normally not both. The only exception to this is that %% can be
163 mixed with the %n$ form. The results of mixing numbered and unnumbered
164 argument specifications in a format string are undefined. When numbered
165 argument specifications are used, specifying the Nth argument requires
166 that all the leading arguments, from the first to the (N-1)th, are
167 specified in the format string.
168
169 Flag Characters
170 The flag characters and their meanings are:
171
172 ' The integer portion of the result of a decimal conversion
173 (%i, %d, %u, %f, %F, %g, or %G) will be formatted with
174 thousands' grouping characters. For other conversions the
175 behavior is undefined. The non-monetary grouping character
176 is used.
177
178 - The result of the conversion will be left-justified within
179 the field. The conversion will be right-justified if this
180 flag is not specified.
181
182 + The result of a signed conversion will always begin with a
183 sign (+ or -). The conversion will begin with a sign only
184 when a negative value is converted if this flag is not
185 specified.
186
187 " " (space) If the first character of a signed conversion is not a sign
188 or if a signed conversion results in no characters, a space
189 will be placed before the result. This means that if the
190 space and + flags both appear, the space flag will be
191 ignored.
192
193 # The value is to be converted to an alternate form. For c,
194 d, i, s, and u conversions, the flag has no effect. For an
195 o conversion, it increases the precision (if necessary) to
196 force the first digit of the result to be a zero. For x or
197 X conversion, a non-zero result will have `0x' (or `0X')
198 prepended to it. For a, A, e, E, f, F, g, and G
199 conversions, the result will always contain a radix
200 character, even if no digits follow the radix character.
201 Without this flag, the radix character appears in the result
202 of these conversions only if a digit follows it. For g and
203 G conversions, trailing zeros will not be removed from the
204 result as they normally are.
205
206 0 For d, i, o, u, x, X, a, A, e, E, f, F, g, and G
207 conversions, leading zeros (following any indication of sign
208 or base) are used to pad to the field width; no space
209 padding is performed. If the 0 and - flags both appear, the
210 0 flag will be ignored. For d, i, o, u, x, and X
211 conversions, if a precision is specified, the 0 flag will be
212 ignored. If the 0 and ' flags both appear, the grouping
213 characters are inserted before zero padding. For other
214 conversions, the behavior is undefined.
215
216 Length Modifiers
217 The length modifiers and their meanings are:
218
219 hh Specifies that a following d, i, o, u, x, or X conversion
220 specifier applies to a signed char or unsigned char
221 argument (the argument will have been promoted according to
222 the integer promotions, but its value will be converted to
223 signed char or unsigned char before printing); or that a
224 following n conversion specifier applies to a pointer to a
225 signed char argument.
226
227 h Specifies that a following d, i, o, u, x, or X conversion
228 specifier applies to a short or unsigned short argument
229 (the argument will have been promoted according to the
230 integer promotions, but its value will be converted to
231 short or unsigned short before printing); or that a
232 following n conversion specifier applies to a pointer to a
233 short argument.
234
235 l (ell) Specifies that a following d, i, o, u, x, or X conversion
236 specifier applies to a long or unsigned long argument; that
237 a following n conversion specifier applies to a pointer to
238 a long argument; that a following c conversion specifier
239 applies to a wint_t argument; that a following s conversion
240 specifier applies to a pointer to a wchar_t argument; or
241 has no effect on a following a, A, e, E, f, F, g, or G
242 conversion specifier.
243
244 ll (ell-ell) Specifies that a following d, i, o, u, x, or X conversion
245 specifier applies to a long long or unsigned long long
246 argument; or that a following n conversion specifier
247 applies to a pointer to a long long argument.
248
249 j Specifies that a following d, i, o, u, x, or X conversion
250 specifier applies to an intmax_t or uintmax_t argument; or
251 that a following n conversion specifier applies to a
252 pointer to an intmax_t argument. See NOTES.
253
254 z Specifies that a following d, i, o, u, x, or X conversion
255 specifier applies to a size_t or the corresponding signed
256 integer type argument; or that a following n conversion
257 specifier applies to a pointer to a signed integer type
258 corresponding to size_t argument.
259
260 t Specifies that a following d, i, o, u, x, or X conversion
261 specifier applies to a ptrdiff_t or the corresponding
262 unsigned type argument; or that a following n conversion
263 specifier applies to a pointer to a ptrdiff_t argument.
264
265 L Specifies that a following a, A, e, E, f, F, g, or G
266 conversion specifier applies to a long double argument.
267
268 If a length modifier appears with any conversion specifier other than as
269 specified above, the behavior is undefined.
270
271 Conversion Specifiers
272 Each conversion specifier results in fetching zero or more arguments.
273 The results are undefined if there are insufficient arguments for the
274 format. If the format is exhausted while arguments remain, the excess
275 arguments are ignored.
276
277 The conversion specifiers and their meanings are:
278
279 d, i The int argument is converted to a signed decimal in the style
280 `[-]dddd'. The precision specifies the minimum number of digits to
281 appear; if the value being converted can be represented in fewer
282 digits, it will be expanded with leading zeros. The default
283 precision is 1. The result of converting 0 with an explicit
284 precision of 0 is no characters.
285
286 o The unsigned int argument is converted to unsigned octal format in
287 the style `dddd'. The precision specifies the minimum number of
288 digits to appear; if the value being converted can be represented
289 in fewer digits, it will be expanded with leading zeros. The
290 default precision is 1. The result of converting 0 with an
291 explicit precision of 0 is no characters.
292
293 u The unsigned int argument is converted to unsigned decimal format
294 in the style `dddd'. The precision specifies the minimum number of
295 digits to appear; if the value being converted can be represented
296 in fewer digits, it will be expanded with leading zeros. The
297 default precision is 1. The result of converting 0 with an
298 explicit precision of 0 is no characters.
299
300 x The unsigned int argument is converted to unsigned hexadecimal
301 format in the style `dddd'; the letters `abcdef' are used. The
302 precision specifies the minimum number of digits to appear; if the
303 value being converted can be represented in fewer digits, it will
304 be expanded with leading zeros. The default precision is 1. The
305 result of converting 0 with an explicit precision of 0 is no
306 characters.
307
308 X Behaves the same as the x conversion specifier except that letters
309 `ABCDEF' are used instead of `abcdef'.
310
311 f, F The double argument is converted to decimal notation in the style
312 `[-]ddd.ddd', where the number of digits after the radix character
313 (see setlocale(3C)) is equal to the precision specification. If
314 the precision is missing it is taken as 6; if the precision is
315 explicitly 0 and the # flag is not specified, no radix character
316 appears. If a radix character appears, at least 1 digit appears
317 before it. The converted value is rounded to fit the specified
318 output format according to the prevailing floating point rounding
319 direction mode. If the conversion is not exact, an inexact
320 exception is raised.
321
322 For the f specifier, a double argument representing an infinity or
323 NaN is converted in the style of the e conversion specifier, except
324 that for an infinite argument, `infinity' or `Infinity' is printed
325 when the precision is at least 8 and `inf' or `Inf' is printed
326 otherwise.
327
328 For the F specifier, a double argument representing an infinity or
329 NaN is converted in the SUSv3 style of the E conversion specifier,
330 except that for an infinite argument, `INFINITY' is printed when
331 the precision is at least 8 and `INF' is printed otherwise.
332
333 e, E The double argument is converted to the style `[-]d.ddde+-dd',
334 where there is one digit before the radix character (which is non-
335 zero if the argument is non-zero) and the number of digits after it
336 is equal to the precision. When the precision is missing it is
337 taken as 6; if the precision is 0 and the # flag is not specified,
338 no radix character appears. The E conversion specifier will
339 produce a number with `E' instead of `e' introducing the exponent.
340 The exponent always contains at least two digits. The converted
341 value is rounded to fit the specified output format according to
342 the prevailing floating point rounding direction mode. If the
343 conversion is not exact, an inexact exception is raised.
344
345 Infinity and NaN values are handled in one of the following ways:
346
347 SUSv3 For the e specifier, a double argument representing an
348 infinity is printed as `[-]infinity', when the precision
349 for the conversion is at least 7 and as `[-]inf'
350 otherwise. A double argument representing a NaN is
351 printed as `[-]nan'. For the E specifier, `INF',
352 `INFINITY', and `NAN' are printed instead of `inf',
353 `infinity', and `nan', respectively. Printing of the sign
354 follows the rules described above.
355
356 Default A double argument representing an infinity is printed as
357 `[-]Infinity', when the precision for the conversion is at
358 least 7 and as `[-]Inf' otherwise. A double argument
359 representing a NaN is printed as `[-]NaN'. Printing of
360 the sign follows the rules described above.
361
362 g, G The double argument is printed in style f or e (or in style E in
363 the case of a G conversion specifier), with the precision
364 specifying the number of significant digits. If an explicit
365 precision is 0, it is taken as 1. The style used depends on the
366 value converted: style e (or E) will be used only if the exponent
367 resulting from the conversion is less than -4 or greater than or
368 equal to the precision. Trailing zeros are removed from the
369 fractional part of the result. A radix character appears only if
370 it is followed by a digit.
371
372 A double argument representing an infinity or NaN is converted in
373 the style of the e or E conversion specifier, except that for an
374 infinite argument, `infinity', `INFINITY', or `Infinity' is printed
375 when the precision is at least 8 and `inf', `INF', or `Inf' is
376 printed otherwise.
377
378 a, A A double argument representing a floating-point number is converted
379 in the style `[-]0xh.hhhhp+-d', where the single hexadecimal digit
380 preceding the radix point is 0 if the value converted is zero and 1
381 otherwise and the number of hexadecimal digits after it is equal to
382 the precision; if the precision is missing, the number of digits
383 printed after the radix point is 13 for the conversion of a double
384 value, 16 for the conversion of a long double value on x86, and 28
385 for the conversion of a long double value on SPARC; if the
386 precision is zero and the # flag is not specified, no decimal-point
387 character will appear. The letters `abcdef' are used for a
388 conversion and the letters `ABCDEF' for A conversion. The A
389 conversion specifier produces a number with `X' and `P' instead of
390 `x' and `p'. The exponent will always contain at least one digit,
391 and only as many more digits as necessary to represent the decimal
392 exponent of 2. If the value is zero, the exponent is zero.
393
394 The converted value is rounded to fit the specified output format
395 according to the prevailing floating point rounding direction mode.
396 If the conversion is not exact, an inexact exception is raised.
397
398 A double argument representing an infinity or NaN is converted in
399 the SUSv3 style of an e or E conversion specifier.
400
401 c The int argument is converted to an unsigned char, and the
402 resulting byte is printed.
403
404 If an l (ell) qualifier is present, the wint_t argument is
405 converted as if by an ls conversion specification with no precision
406 and an argument that points to a two-element array of type wchar_t,
407 the first element of which contains the wint_t argument to the ls
408 conversion specification and the second element contains a null
409 wide-character.
410
411 C Same as lc.
412
413 wc The int argument is converted to a wide character (wchar_t), and
414 the resulting wide character is printed.
415
416 s The argument must be a pointer to an array of char. Bytes from the
417 array are written up to (but not including) any terminating null
418 byte. If a precision is specified, a standard-conforming
419 application (see standards(5)) will write only the number of bytes
420 specified by precision; an application that is not standard-
421 conforming will write only the portion of the string that will
422 display in the number of columns of screen display specified by
423 precision. If the precision is not specified, it is taken to be
424 infinite, so all bytes up to the first null byte are printed. An
425 argument with a null value will yield undefined results.
426
427 If an l (ell) qualifier is present, the argument must be a pointer
428 to an array of type wchar_t. Wide-characters from the array are
429 converted to characters (each as if by a call to the wcrtomb(3C)
430 function, with the conversion state described by an mbstate_t
431 object initialized to zero before the first wide-character is
432 converted) up to and including a terminating null wide-character.
433 The resulting characters are written up to (but not including) the
434 terminating null character (byte). If no precision is specified,
435 the array must contain a null wide-character. If a precision is
436 specified, no more than that many characters (bytes) are written
437 (including shift sequences, if any), and the array must contain a
438 null wide-character if, to equal the character sequence length
439 given by the precision, the function would need to access a wide-
440 character one past the end of the array. In no case is a partial
441 character written.
442
443 S Same as ls.
444
445 ws The argument must be a pointer to an array of wchar_t. Bytes from
446 the array are written up to (but not including) any terminating
447 null character. If the precision is specified, only that portion
448 of the wide-character array that will display in the number of
449 columns of screen display specified by precision will be written.
450 If the precision is not specified, it is taken to be infinite, so
451 all wide characters up to the first null character are printed. An
452 argument with a null value will yield undefined results.
453
454 p The argument must be a pointer to void. The value of the pointer
455 is converted to a set of sequences of printable characters, which
456 should be the same as the set of sequences that are matched by the
457 %p conversion of the scanf(3C) function.
458
459 n The argument must be a pointer to an integer into which is written
460 the number of bytes written to the output standard I/O stream so
461 far by this call to one of the printf() functions. No argument is
462 converted.
463
464 % Print a `%'; no argument is converted. The entire conversion
465 specification must be %%.
466
467 If a conversion specification does not match one of the above forms, the
468 behavior is undefined.
469
470 In no case does a non-existent or small field width cause truncation of a
471 field; if the result of a conversion is wider than the field width, the
472 field is simply expanded to contain the conversion result. Characters
473 generated by printf() and fprintf() are printed as if the putc(3C)
474 function had been called.
475
476 The st_ctime and st_mtime fields of the file will be marked for update
477 between the call to a successful execution of printf() or fprintf() and
478 the next successful completion of a call to fflush(3C) or fclose(3C) on
479 the same stream or a call to exit(3C) or abort(3C).
480
481 RETURN VALUES
482 The printf(), fprintf(), sprintf(), and asprintf() functions return the
483 number of bytes transmitted (excluding the terminating null byte in the
484 case of sprintf() and asprintf()).
485
486 The snprintf() function returns the number of bytes that would have been
487 written to s if n had been sufficiently large (excluding the terminating
488 null byte). If the value of n is 0 on a call to snprintf(), s can be a
489 null pointer and the number of bytes that would have been written if n
490 had been sufficiently large (excluding the terminating null byte) is
491 returned.
492
493 Each function returns a negative value if an output error was
494 encountered.
495
496 USAGE
497 If the application calling the printf() functions has any objects of type
498 wint_t or wchar_t, it must also include the header <wchar.h> to have
499 these objects defined.
500
501 Escape Character Sequences
502 It is common to use the following escape sequences built into the C
503 language when entering format strings for the printf() functions, but
504 these sequences are processed by the C compiler, not by the printf()
505 function.
506
507 \a Alert. Ring the bell.
508
509 \b Backspace. Move the printing position to one character before the
510 current position, unless the current position is the start of a line.
511
512 \f Form feed. Move the printing position to the initial printing
513 position of the next logical page.
514
515 \n Newline. Move the printing position to the start of the next line.
516
517 \r Carriage return. Move the printing position to the start of the
518 current line.
519
520 \t Horizontal tab. Move the printing position to the next
521 implementation-defined horizontal tab position on the current line.
522
523 \v Vertical tab. Move the printing position to the start of the next
524 implementation-defined vertical tab position.
525
526 In addition, the C language supports character sequences of the form
527 \octal-number and \hex-number which translates into the character
528 represented by the octal or hexadecimal number. For example, if ASCII
529 representations are being used, the letter 'a' may be written as `\141'
530 and 'Z' as `\132'. This syntax is most frequently used to represent the
531 null character as `\0'. This is exactly equivalent to the numeric
532 constant zero (0). Note that the octal number does not include the zero
533 prefix as it would for a normal octal constant. To specify a hexadecimal
534 number, omit the zero so that the prefix is an 'x' (uppercase 'X' is not
535 allowed in this context). Support for hexadecimal sequences is an ANSI
536 extension. See standards(5).
537
538 EXAMPLES
539 Example 1 To print the language-independent date and time format, the
540 following statement could be used:
541
542 printf (format, weekday, month, day, hour, min);
543
544 For American usage, format could be a pointer to the string:
545
546 "%s, %s %d, %d:%.2d\n"
547
548 producing the message:
549
550 Sunday, July 3, 10:02
551
552 whereas for German usage, format could be a pointer to the string:
553
554 "%1$s, %3$d. %2$s, %4$d:%5$.2d\n"
555
556 producing the message:
557
558 Sonntag, 3. Juli, 10:02
559
560 Example 2 To print a date and time in the form `Sunday, July 3, 10:02',
561 where weekday and month are pointers to null-terminated strings:
562
563 printf("%s, %s %i, %d:%.2d", weekday, month, day, hour, min);
564
565 Example 3 To print pi to 5 decimal places:
566
567 printf("pi = %.5f", 4 * atan(1.0));
568
569 Example 4 The following example applies only to applications that are not
570 standard-conforming. To print a list of names in columns which are 20
571 characters wide:
572
573 printf("%20s%20s%20s", lastname, firstname, middlename);
574
575 ERRORS
576 For the conditions under which printf() and fprintf() will fail and may
577 fail, refer to fputc(3C) or fputwc(3C).
578
579 The snprintf() function will fail if:
580
581 EOVERFLOW The value of n is greater than INT_MAX or the number
582 of bytes needed to hold the output excluding the
583 terminating null is greater than INT_MAX.
584
585 The printf(), fprintf(), sprintf(), and snprintf() functions may fail if:
586
587 EILSEQ A wide-character code that does not correspond to a
588 valid character has been detected.
589
590 EINVAL There are insufficient arguments.
591
592 The printf(), fprintf(), and asprintf() functions may fail due to an
593 underlying malloc(3C) failure if:
594
595 EAGAIN Storage space is temporarily unavailable.
596
597 ENOMEM Insufficient storage space is available.
598
599 CODE SET INDEPENDENCE
600 Enabled
601
602 INTERFACE STABILITY
603 Committed
604
605 MT-LEVEL
606 All of these functions can be used safely in multithreaded applications,
607 as long as setlocale(3C) is not being called to change the locale. The
608 sprintf() and snprintf() functions are Async-Signal-Safe.
609
610 SEE ALSO
611 exit(2), lseek(2), write(2), abort(3C), ecvt(3C), exit(3C), fclose(3C),
612 fflush(3C), fputwc(3C), free(3C), malloc(3C), putc(3C), scanf(3C),
613 setlocale(3C), stdio(3C), vprintf(3C), wcstombs(3C), wctomb(3C),
614 attributes(5), environ(5), standards(5)
615
616 STANDARDS
617 See standards(5) for the standards conformance of printf(), fprintf(),
618 sprintf(), and snprintf(). The asprintf() function is modeled on the one
619 that appears in the FreeBSD, NetBSD, and GNU C libraries.
620
621 NOTES
622 If the j length modifier is used, 32-bit applications that were compiled
623 using c89 on releases prior to Solaris 10 will experience undefined
624 behavior.
625
626 The snprintf() return value when n is 0 was changed in the Solaris 10
627 release. The change was based on the SUSv3 specification. The previous
628 behavior was based on the initial SUSv2 specification, where snprintf()
629 when n is 0 returns an unspecified value less than 1.
630
631 illumos July 10, 2020 illumos
|