1 /*
2 * Copyright (c) 1990 The Regents of the University of California.
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms are permitted
6 * provided that the above copyright notice and this paragraph are
7 * duplicated in all such forms and that any documentation,
8 * and/or other materials related to such
9 * distribution and use acknowledge that the software was developed
10 * by the University of California, Berkeley. The name of the
11 * University may not be used to endorse or promote products derived
12 * from this software without specific prior written permission.
13 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR
14 * IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
15 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
16 */
17
18 /*
19 FUNCTION
20 <<sprintf>>, <<fprintf>>, <<printf>>, <<snprintf>>, <<asprintf>>, <<asnprintf>>---format output
21
22 INDEX
23 fprintf
24 INDEX
25 _fprintf_r
26 INDEX
27 printf
28 INDEX
29 _printf_r
30 INDEX
31 asprintf
32 INDEX
33 _asprintf_r
34 INDEX
35 sprintf
36 INDEX
37 _sprintf_r
38 INDEX
39 snprintf
40 INDEX
41 _snprintf_r
42 INDEX
43 asnprintf
44 INDEX
45 _asnprintf_r
46
47 SYNOPSIS
48 #include <stdio.h>
49
50 int printf(const char *restrict <[format]>, ...);
51 int fprintf(FILE *restrict <[fd]>, const char *restrict <[format]>, ...);
52 int sprintf(char *restrict <[str]>, const char *restrict <[format]>, ...);
53 int snprintf(char *restrict <[str]>, size_t <[size]>, const char *restrict <[format]>,
54 ...);
55 int asprintf(char **restrict <[strp]>, const char *restrict <[format]>, ...);
56 char *asnprintf(char *restrict <[str]>, size_t *restrict <[size]>, const char *restrict <[format]>,
57 ...);
58
59 int printf( const char *restrict <[format]>, ...);
60 int fprintf( FILE *restrict <[fd]>,
61 const char *restrict <[format]>, ...);
62 int sprintf( char *restrict <[str]>,
63 const char *restrict <[format]>, ...);
64 int snprintf( char *restrict <[str]>, size_t <[size]>,
65 const char *restrict <[format]>, ...);
66 int asprintf( char **restrict <[strp]>,
67 const char *restrict <[format]>, ...);
68 char *asnprintf( char *restrict <[str]>,
69 size_t *restrict <[size]>, const char *restrict <[format]>, ...);
70
71 DESCRIPTION
72 <<printf>> accepts a series of arguments, applies to each a
73 format specifier from <<*<[format]>>>, and writes the
74 formatted data to <<stdout>>, without a terminating NUL
75 character. The behavior of <<printf>> is undefined if there
76 are not enough arguments for the format. <<printf>> returns
77 when it reaches the end of the format string. If there are
78 more arguments than the format requires, excess arguments are
79 ignored.
80
81 <<fprintf>> is like <<printf>>, except that output is directed
82 to the stream <[fd]> rather than <<stdout>>.
83
84 <<sprintf>> is like <<printf>>, except that output is directed
85 to the buffer <[str]>, and a terminating NUL is output.
86 Behavior is undefined if more output is generated than the
87 buffer can hold.
88
89 <<snprintf>> is like <<sprintf>>, except that output is
90 limited to at most <[size]> bytes, including the terminating
91 <<NUL>>. As a special case, if <[size]> is 0, <[str]> can be
92 NULL, and <<snprintf>> merely calculates how many bytes would
93 be printed.
94
95 <<asprintf>> is like <<sprintf>>, except that the output is
96 stored in a dynamically allocated buffer, <[pstr]>, which
97 should be freed later with <<free>>.
98
99 <<asnprintf>> is like <<sprintf>>, except that the return type
100 is either the original <[str]> if it was large enough, or a
101 dynamically allocated string if the output exceeds *<[size]>;
102 the length of the result is returned in *<[size]>. When
103 dynamic allocation occurs, the contents of the original
104 <[str]> may have been modified.
105
106 For <<sprintf>>, <<snprintf>>, and <<asnprintf>>, the behavior
107 is undefined if the output <<*<[str]>>> overlaps with one of
108 the arguments. Behavior is also undefined if the argument for
109 <<%n>> within <<*<[format]>>> overlaps another argument.
110
111 <[format]> is a pointer to a character string containing two
112 types of objects: ordinary characters (other than <<%>>),
113 which are copied unchanged to the output, and conversion
114 specifications, each of which is introduced by <<%>>. (To
115 include <<%>> in the output, use <<%%>> in the format string.)
116 A conversion specification has the following form:
117
118 . %[<[pos]>][<[flags]>][<[width]>][.<[prec]>][<[size]>]<[type]>
119
120 The fields of the conversion specification have the following
121 meanings:
122
123 O+
124 o <[pos]>
125
126 Conversions normally consume arguments in the order that they
127 are presented. However, it is possible to consume arguments
128 out of order, and reuse an argument for more than one
129 conversion specification (although the behavior is undefined
130 if the same argument is requested with different types), by
131 specifying <[pos]>, which is a decimal integer followed by
132 '$'. The integer must be between 1 and <NL_ARGMAX> from
133 limits.h, and if argument <<%n$>> is requested, all earlier
134 arguments must be requested somewhere within <[format]>. If
135 positional parameters are used, then all conversion
136 specifications except for <<%%>> must specify a position.
137 This positional parameters method is a POSIX extension to the C
138 standard definition for the functions.
139
140 o <[flags]>
141
142 <[flags]> is an optional sequence of characters which control
143 output justification, numeric signs, decimal points, trailing
144 zeros, and octal and hex prefixes. The flag characters are
145 minus (<<->>), plus (<<+>>), space ( ), zero (<<0>>), sharp
146 (<<#>>), and quote (<<'>>). They can appear in any
147 combination, although not all flags can be used for all
148 conversion specification types.
149
150 o+
151 o '
152 A POSIX extension to the C standard. However, this
153 implementation presently treats it as a no-op, which
154 is the default behavior for the C locale, anyway. (If
155 it did what it is supposed to, when <[type]> were <<i>>,
156 <<d>>, <<u>>, <<f>>, <<F>>, <<g>>, or <<G>>, the
157 integer portion of the conversion would be formatted
158 with thousands' grouping wide characters.)
159
160 o -
161 The result of the conversion is left
162 justified, and the right is padded with
163 blanks. If you do not use this flag, the
164 result is right justified, and padded on the
165 left.
166
167 o +
168 The result of a signed conversion (as
169 determined by <[type]> of <<d>>, <<i>>, <<a>>,
170 <<A>>, <<e>>, <<E>>, <<f>>, <<F>>, <<g>>, or
171 <<G>>) will always begin with a plus or minus
172 sign. (If you do not use this flag, positive
173 values do not begin with a plus sign.)
174
175 o " " (space)
176 If the first character of a signed conversion
177 specification is not a sign, or if a signed
178 conversion results in no characters, the
179 result will begin with a space. If the space
180 ( ) flag and the plus (<<+>>) flag both
181 appear, the space flag is ignored.
182
183 o 0
184 If the <[type]> character is <<d>>, <<i>>,
185 <<o>>, <<u>>, <<x>>, <<X>>, <<a>>, <<A>>,
186 <<e>>, <<E>>, <<f>>, <<F>>, <<g>>, or <<G>>: leading
187 zeros are used to pad the field width
188 (following any indication of sign or base); no
189 spaces are used for padding. If the zero
190 (<<0>>) and minus (<<->>) flags both appear,
191 the zero (<<0>>) flag will be ignored. For
192 <<d>>, <<i>>, <<o>>, <<u>>, <<x>>, and <<X>>
193 conversions, if a precision <[prec]> is
194 specified, the zero (<<0>>) flag is ignored.
195
196 Note that <<0>> is interpreted as a flag, not
197 as the beginning of a field width.
198
199 o #
200 The result is to be converted to an
201 alternative form, according to the <[type]>
202 character.
203 o-
204
205 The alternative form output with the # flag depends on the <[type]>
206 character:
207
208 o+
209 o o
210 Increases precision to force the first
211 digit of the result to be a zero.
212
213 o x
214 A non-zero result will have a <<0x>>
215 prefix.
216
217 o X
218 A non-zero result will have a <<0X>>
219 prefix.
220
221 o a, A, e, E, f, or F
222 The result will always contain a
223 decimal point even if no digits follow
224 the point. (Normally, a decimal point
225 appears only if a digit follows it.)
226 Trailing zeros are removed.
227
228 o g or G
229 The result will always contain a
230 decimal point even if no digits follow
231 the point. Trailing zeros are not
232 removed.
233
234 o all others
235 Undefined.
236
237 o-
238
239 o <[width]>
240
241 <[width]> is an optional minimum field width. You can
242 either specify it directly as a decimal integer, or
243 indirectly by using instead an asterisk (<<*>>), in
244 which case an <<int>> argument is used as the field
245 width. If positional arguments are used, then the
246 width must also be specified positionally as <<*m$>>,
247 with m as a decimal integer. Negative field widths
248 are treated as specifying the minus (<<->>) flag for
249 left justfication, along with a positive field width.
250 The resulting format may be wider than the specified
251 width.
252
253 o <[prec]>
254
255 <[prec]> is an optional field; if present, it is
256 introduced with `<<.>>' (a period). You can specify
257 the precision either directly as a decimal integer or
258 indirectly by using an asterisk (<<*>>), in which case
259 an <<int>> argument is used as the precision. If
260 positional arguments are used, then the precision must
261 also be specified positionally as <<*m$>>, with m as a
262 decimal integer. Supplying a negative precision is
263 equivalent to omitting the precision. If only a
264 period is specified the precision is zero. The effect
265 depends on the conversion <[type]>.
266
267 o+
268 o d, i, o, u, x, or X
269 Minimum number of digits to appear. If no
270 precision is given, defaults to 1.
271
272 o a or A
273 Number of digits to appear after the decimal
274 point. If no precision is given, the
275 precision defaults to the minimum needed for
276 an exact representation.
277
278 o e, E, f or F
279 Number of digits to appear after the decimal
280 point. If no precision is given, the
281 precision defaults to 6.
282
283 o g or G
284 Maximum number of significant digits. A
285 precision of 0 is treated the same as a
286 precision of 1. If no precision is given, the
287 precision defaults to 6.
288
289 o s or S
290 Maximum number of characters to print from the
291 string. If no precision is given, the entire
292 string is printed.
293
294 o all others
295 undefined.
296
297 o-
298
299 o <[size]>
300
301 <[size]> is an optional modifier that changes the data
302 type that the corresponding argument has. Behavior is
303 unspecified if a size is given that does not match the
304 <[type]>.
305
306 o+
307 o hh
308 With <<d>>, <<i>>, <<o>>, <<u>>, <<x>>, or
309 <<X>>, specifies that the argument should be
310 converted to a <<signed char>> or <<unsigned
311 char>> before printing.
312
313 With <<n>>, specifies that the argument is a
314 pointer to a <<signed char>>.
315
316 o h
317 With <<d>>, <<i>>, <<o>>, <<u>>, <<x>>, or
318 <<X>>, specifies that the argument should be
319 converted to a <<short>> or <<unsigned short>>
320 before printing.
321
322 With <<n>>, specifies that the argument is a
323 pointer to a <<short>>.
324
325 o l
326 With <<d>>, <<i>>, <<o>>, <<u>>, <<x>>, or
327 <<X>>, specifies that the argument is a
328 <<long>> or <<unsigned long>>.
329
330 With <<c>>, specifies that the argument has
331 type <<wint_t>>.
332
333 With <<s>>, specifies that the argument is a
334 pointer to <<wchar_t>>.
335
336 With <<n>>, specifies that the argument is a
337 pointer to a <<long>>.
338
339 With <<a>>, <<A>>, <<e>>, <<E>>, <<f>>, <<F>>,
340 <<g>>, or <<G>>, has no effect (because of
341 vararg promotion rules, there is no need to
342 distinguish between <<float>> and <<double>>).
343
344 o ll
345 With <<d>>, <<i>>, <<o>>, <<u>>, <<x>>, or
346 <<X>>, specifies that the argument is a
347 <<long long>> or <<unsigned long long>>.
348
349 With <<n>>, specifies that the argument is a
350 pointer to a <<long long>>.
351
352 o j
353 With <<d>>, <<i>>, <<o>>, <<u>>, <<x>>, or
354 <<X>>, specifies that the argument is an
355 <<intmax_t>> or <<uintmax_t>>.
356
357 With <<n>>, specifies that the argument is a
358 pointer to an <<intmax_t>>.
359
360 o z
361 With <<d>>, <<i>>, <<o>>, <<u>>, <<x>>, or
362 <<X>>, specifies that the argument is a <<size_t>>.
363
364 With <<n>>, specifies that the argument is a
365 pointer to a <<size_t>>.
366
367 o t
368 With <<d>>, <<i>>, <<o>>, <<u>>, <<x>>, or
369 <<X>>, specifies that the argument is a
370 <<ptrdiff_t>>.
371
372 With <<n>>, specifies that the argument is a
373 pointer to a <<ptrdiff_t>>.
374
375 o L
376 With <<a>>, <<A>>, <<e>>, <<E>>, <<f>>, <<F>>,
377 <<g>>, or <<G>>, specifies that the argument
378 is a <<long double>>.
379
380 o-
381
382 o <[type]>
383
384 <[type]> specifies what kind of conversion <<printf>>
385 performs. Here is a table of these:
386
387 o+
388 o %
389 Prints the percent character (<<%>>).
390
391 o c
392 Prints <[arg]> as single character. If the
393 <<l>> size specifier is in effect, a multibyte
394 character is printed.
395
396 o C
397 Short for <<%lc>>. A POSIX extension to the C standard.
398
399 o s
400 Prints the elements of a pointer to <<char>>
401 until the precision or a null character is
402 reached. If the <<l>> size specifier is in
403 effect, the pointer is to an array of
404 <<wchar_t>>, and the string is converted to
405 multibyte characters before printing.
406
407 o S
408 Short for <<%ls>>. A POSIX extension to the C standard.
409
410 o d or i
411 Prints a signed decimal integer; takes an
412 <<int>>. Leading zeros are inserted as
413 necessary to reach the precision. A value of 0 with
414 a precision of 0 produces an empty string.
415
416 o D
417 Newlib extension, short for <<%ld>>.
418
419 o o
420 Prints an unsigned octal integer; takes an
421 <<unsigned>>. Leading zeros are inserted as
422 necessary to reach the precision. A value of 0 with
423 a precision of 0 produces an empty string.
424
425 o O
426 Newlib extension, short for <<%lo>>.
427
428 o u
429 Prints an unsigned decimal integer; takes an
430 <<unsigned>>. Leading zeros are inserted as
431 necessary to reach the precision. A value of 0 with
432 a precision of 0 produces an empty string.
433
434 o U
435 Newlib extension, short for <<%lu>>.
436
437 o x
438 Prints an unsigned hexadecimal integer (using
439 <<abcdef>> as digits beyond <<9>>); takes an
440 <<unsigned>>. Leading zeros are inserted as
441 necessary to reach the precision. A value of 0 with
442 a precision of 0 produces an empty string.
443
444 o X
445 Like <<x>>, but uses <<ABCDEF>> as digits
446 beyond <<9>>.
447
448 o f
449 Prints a signed value of the form
450 <<[-]9999.9999>>, with the precision
451 determining how many digits follow the decimal
452 point; takes a <<double>> (remember that
453 <<float>> promotes to <<double>> as a vararg).
454 The low order digit is rounded to even. If
455 the precision results in at most DECIMAL_DIG
456 digits, the result is rounded correctly; if
457 more than DECIMAL_DIG digits are printed, the
458 result is only guaranteed to round back to the
459 original value.
460
461 If the value is infinite, the result is
462 <<inf>>, and no zero padding is performed. If
463 the value is not a number, the result is
464 <<nan>>, and no zero padding is performed.
465
466 o F
467 Like <<f>>, but uses <<INF>> and <<NAN>> for
468 non-finite numbers.
469
470 o e
471 Prints a signed value of the form
472 <<[-]9.9999e[+|-]999>>; takes a <<double>>.
473 The digit before the decimal point is non-zero
474 if the value is non-zero. The precision
475 determines how many digits appear between
476 <<.>> and <<e>>, and the exponent always
477 contains at least two digits. The value zero
478 has an exponent of zero. If the value is not
479 finite, it is printed like <<f>>.
480
481 o E
482 Like <<e>>, but using <<E>> to introduce the
483 exponent, and like <<F>> for non-finite
484 values.
485
486 o g
487 Prints a signed value in either <<f>> or <<e>>
488 form, based on the given value and
489 precision---an exponent less than -4 or
490 greater than the precision selects the <<e>>
491 form. Trailing zeros and the decimal point
492 are printed only if necessary; takes a
493 <<double>>.
494
495 o G
496 Like <<g>>, except use <<F>> or <<E>> form.
497
498 o a
499 Prints a signed value of the form
500 <<[-]0x1.ffffp[+|-]9>>; takes a <<double>>.
501 The letters <<abcdef>> are used for digits
502 beyond <<9>>. The precision determines how
503 many digits appear after the decimal point.
504 The exponent contains at least one digit, and
505 is a decimal value representing the power of
506 2; a value of 0 has an exponent of 0.
507 Non-finite values are printed like <<f>>.
508
509 o A
510 Like <<a>>, except uses <<X>>, <<P>>, and
511 <<ABCDEF>> instead of lower case.
512
513 o n
514 Takes a pointer to <<int>>, and stores a count
515 of the number of bytes written so far. No
516 output is created.
517
518 o p
519 Takes a pointer to <<void>>, and prints it in
520 an implementation-defined format. This
521 implementation is similar to <<%#tx>>), except
522 that <<0x>> appears even for the NULL pointer.
523
524 o m
525 Prints the output of <<strerror(errno)>>; no
526 argument is required. A GNU extension.
527
528 o-
529 O-
530
531 <<_printf_r>>, <<_fprintf_r>>, <<_asprintf_r>>,
532 <<_sprintf_r>>, <<_snprintf_r>>, <<_asnprintf_r>> are simply
533 reentrant versions of the functions above.
534
535 RETURNS
536 On success, <<sprintf>> and <<asprintf>> return the number of bytes in
537 the output string, except the concluding <<NUL>> is not counted.
538 <<snprintf>> returns the number of bytes that would be in the output
539 string, except the concluding <<NUL>> is not counted. <<printf>> and
540 <<fprintf>> return the number of characters transmitted.
541 <<asnprintf>> returns the original <[str]> if there was enough room,
542 otherwise it returns an allocated string.
543
544 If an error occurs, the result of <<printf>>, <<fprintf>>,
545 <<snprintf>>, and <<asprintf>> is a negative value, and the result of
546 <<asnprintf>> is NULL. No error returns occur for <<sprintf>>. For
547 <<printf>> and <<fprintf>>, <<errno>> may be set according to
548 <<fputc>>. For <<asprintf>> and <<asnprintf>>, <<errno>> may be set
549 to ENOMEM if allocation fails, and for <<snprintf>>, <<errno>> may be
550 set to EOVERFLOW if <[size]> or the output length exceeds INT_MAX.
551
552 BUGS
553 The ``''' (quote) flag does not work when locale's thousands_sep is not empty.
554
555 PORTABILITY
556 ANSI C requires <<printf>>, <<fprintf>>, <<sprintf>>, and
557 <<snprintf>>. <<asprintf>> and <<asnprintf>> are newlib extensions.
558
559 The ANSI C standard specifies that implementations must support at
560 least formatted output of up to 509 characters. This implementation
561 has no inherent limit.
562
563 Depending on how newlib was configured, not all format specifiers are
564 supported.
565
566 Supporting OS subroutines required: <<close>>, <<fstat>>, <<isatty>>,
567 <<lseek>>, <<read>>, <<sbrk>>, <<write>>.
568 */
569
570 #define _DEFAULT_SOURCE
571 #include <_ansi.h>
572 #include <stdio.h>
573 #include <stdarg.h>
574 #include <limits.h>
575 #include "local.h"
576
577 #undef sprintf
578
579 int
sprintf(char * __restrict str,const char * __restrict fmt,...)580 sprintf (
581 char *__restrict str,
582 const char *__restrict fmt, ...)
583 {
584 int ret;
585 va_list ap;
586 FILE f;
587
588 f._flags = __SWR | __SSTR;
589 f._bf._base = f._p = (unsigned char *) str;
590 f._bf._size = f._w = INT_MAX;
591 f._file = -1; /* No file. */
592 va_start (ap, fmt);
593 ret = svfprintf ( &f, fmt, ap);
594 va_end (ap);
595 *f._p = '\0'; /* terminate the string */
596 return (ret);
597 }
598
599 #ifdef _NANO_FORMATTED_IO
600 int __nonnull((1, 2)) _NOTHROW
601 siprintf ( char *, const char *, ...)
602 _ATTRIBUTE ((__alias__("sprintf")));
603 #endif
604
