Cygwin: mmap: allow remapping part of an existing anonymous mapping
[newlib-cygwin.git] / newlib / libc / stdio / sprintf.c
blob92cae46189df17f87a57a4a49eb068e309ab114d
1 /*
2 * Copyright (c) 1990 The Regents of the University of California.
3 * All rights reserved.
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.
19 FUNCTION
20 <<sprintf>>, <<fprintf>>, <<printf>>, <<snprintf>>, <<asprintf>>, <<asnprintf>>---format output
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
47 SYNOPSIS
48 #include <stdio.h>
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 ...);
59 int _printf_r(struct _reent *<[ptr]>, const char *restrict <[format]>, ...);
60 int _fprintf_r(struct _reent *<[ptr]>, FILE *restrict <[fd]>,
61 const char *restrict <[format]>, ...);
62 int _sprintf_r(struct _reent *<[ptr]>, char *restrict <[str]>,
63 const char *restrict <[format]>, ...);
64 int _snprintf_r(struct _reent *<[ptr]>, char *restrict <[str]>, size_t <[size]>,
65 const char *restrict <[format]>, ...);
66 int _asprintf_r(struct _reent *<[ptr]>, char **restrict <[strp]>,
67 const char *restrict <[format]>, ...);
68 char *_asnprintf_r(struct _reent *<[ptr]>, char *restrict <[str]>,
69 size_t *restrict <[size]>, const char *restrict <[format]>, ...);
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.
81 <<fprintf>> is like <<printf>>, except that output is directed
82 to the stream <[fd]> rather than <<stdout>>.
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.
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.
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>>.
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.
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.
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:
118 . %[<[pos]>][<[flags]>][<[width]>][.<[prec]>][<[size]>]<[type]>
120 The fields of the conversion specification have the following
121 meanings:
124 o <[pos]>
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.
140 o <[flags]>
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.
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.)
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.
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.)
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.
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.
196 Note that <<0>> is interpreted as a flag, not
197 as the beginning of a field width.
200 The result is to be converted to an
201 alternative form, according to the <[type]>
202 character.
205 The alternative form output with the # flag depends on the <[type]>
206 character:
210 Increases precision to force the first
211 digit of the result to be a zero.
214 A non-zero result will have a <<0x>>
215 prefix.
218 A non-zero result will have a <<0X>>
219 prefix.
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.
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.
234 o all others
235 Undefined.
239 o <[width]>
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.
253 o <[prec]>
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]>.
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.
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.
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.
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.
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.
294 o all others
295 undefined.
299 o <[size]>
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]>.
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.
313 With <<n>>, specifies that the argument is a
314 pointer to a <<signed char>>.
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.
322 With <<n>>, specifies that the argument is a
323 pointer to a <<short>>.
326 With <<d>>, <<i>>, <<o>>, <<u>>, <<x>>, or
327 <<X>>, specifies that the argument is a
328 <<long>> or <<unsigned long>>.
330 With <<c>>, specifies that the argument has
331 type <<wint_t>>.
333 With <<s>>, specifies that the argument is a
334 pointer to <<wchar_t>>.
336 With <<n>>, specifies that the argument is a
337 pointer to a <<long>>.
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>>).
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>>.
349 With <<n>>, specifies that the argument is a
350 pointer to a <<long long>>.
353 With <<d>>, <<i>>, <<o>>, <<u>>, <<x>>, or
354 <<X>>, specifies that the argument is an
355 <<intmax_t>> or <<uintmax_t>>.
357 With <<n>>, specifies that the argument is a
358 pointer to an <<intmax_t>>.
361 With <<d>>, <<i>>, <<o>>, <<u>>, <<x>>, or
362 <<X>>, specifies that the argument is a <<size_t>>.
364 With <<n>>, specifies that the argument is a
365 pointer to a <<size_t>>.
368 With <<d>>, <<i>>, <<o>>, <<u>>, <<x>>, or
369 <<X>>, specifies that the argument is a
370 <<ptrdiff_t>>.
372 With <<n>>, specifies that the argument is a
373 pointer to a <<ptrdiff_t>>.
376 With <<a>>, <<A>>, <<e>>, <<E>>, <<f>>, <<F>>,
377 <<g>>, or <<G>>, specifies that the argument
378 is a <<long double>>.
382 o <[type]>
384 <[type]> specifies what kind of conversion <<printf>>
385 performs. Here is a table of these:
389 Prints the percent character (<<%>>).
392 Prints <[arg]> as single character. If the
393 <<l>> size specifier is in effect, a multibyte
394 character is printed.
397 Short for <<%lc>>. A POSIX extension to the C standard.
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.
408 Short for <<%ls>>. A POSIX extension to the C standard.
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.
417 Newlib extension, short for <<%ld>>.
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.
426 Newlib extension, short for <<%lo>>.
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.
435 Newlib extension, short for <<%lu>>.
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.
445 Like <<x>>, but uses <<ABCDEF>> as digits
446 beyond <<9>>.
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.
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.
467 Like <<f>>, but uses <<INF>> and <<NAN>> for
468 non-finite numbers.
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>>.
482 Like <<e>>, but using <<E>> to introduce the
483 exponent, and like <<F>> for non-finite
484 values.
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>>.
496 Like <<g>>, except use <<F>> or <<E>> form.
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>>.
510 Like <<a>>, except uses <<X>>, <<P>>, and
511 <<ABCDEF>> instead of lower case.
514 Takes a pointer to <<int>>, and stores a count
515 of the number of bytes written so far. No
516 output is created.
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.
525 Prints the output of <<strerror(errno)>>; no
526 argument is required. A GNU extension.
531 <<_printf_r>>, <<_fprintf_r>>, <<_asprintf_r>>,
532 <<_sprintf_r>>, <<_snprintf_r>>, <<_asnprintf_r>> are simply
533 reentrant versions of the functions above.
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.
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.
552 BUGS
553 The ``''' (quote) flag does not work when locale's thousands_sep is not empty.
555 PORTABILITY
556 ANSI C requires <<printf>>, <<fprintf>>, <<sprintf>>, and
557 <<snprintf>>. <<asprintf>> and <<asnprintf>> are newlib extensions.
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.
563 Depending on how newlib was configured, not all format specifiers are
564 supported.
566 Supporting OS subroutines required: <<close>>, <<fstat>>, <<isatty>>,
567 <<lseek>>, <<read>>, <<sbrk>>, <<write>>.
570 #include <_ansi.h>
571 #include <reent.h>
572 #include <stdio.h>
573 #include <stdarg.h>
574 #include <limits.h>
575 #include "local.h"
578 _sprintf_r (struct _reent *ptr,
579 char *__restrict str,
580 const char *__restrict fmt, ...)
582 int ret;
583 va_list ap;
584 FILE f;
586 f._flags = __SWR | __SSTR;
587 f._flags2 = 0;
588 f._bf._base = f._p = (unsigned char *) str;
589 f._bf._size = f._w = INT_MAX;
590 f._file = -1; /* No file. */
591 va_start (ap, fmt);
592 ret = _svfprintf_r (ptr, &f, fmt, ap);
593 va_end (ap);
594 *f._p = '\0'; /* terminate the string */
595 return (ret);
598 #ifdef _NANO_FORMATTED_IO
600 _siprintf_r (struct _reent *, char *, const char *, ...)
601 _ATTRIBUTE ((__alias__("_sprintf_r")));
602 #endif
604 #ifndef _REENT_ONLY
607 sprintf (char *__restrict str,
608 const char *__restrict fmt, ...)
610 int ret;
611 va_list ap;
612 FILE f;
614 f._flags = __SWR | __SSTR;
615 f._flags2 = 0;
616 f._bf._base = f._p = (unsigned char *) str;
617 f._bf._size = f._w = INT_MAX;
618 f._file = -1; /* No file. */
619 va_start (ap, fmt);
620 ret = _svfprintf_r (_REENT, &f, fmt, ap);
621 va_end (ap);
622 *f._p = '\0'; /* terminate the string */
623 return (ret);
626 #ifdef _NANO_FORMATTED_IO
628 siprintf (char *, const char *, ...)
629 _ATTRIBUTE ((__alias__("sprintf")));
630 #endif
631 #endif