source: trunk/libs/newlib/src/newlib/libc/stdio/sprintf.c @ 567

Last change on this file since 567 was 444, checked in by satin@…, 6 years ago

add newlib,libalmos-mkh, restructure shared_syscalls.h and mini-libc
File size: 19.8 KB
Line 
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 * advertising materials, and 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/*
19FUNCTION
20<<sprintf>>, <<fprintf>>, <<printf>>, <<snprintf>>, <<asprintf>>, <<asnprintf>>---format output
21
22INDEX
23        fprintf
24INDEX
25        _fprintf_r
26INDEX
27        printf
28INDEX
29        _printf_r
30INDEX
31        asprintf
32INDEX
33        _asprintf_r
34INDEX
35        sprintf
36INDEX
37        _sprintf_r
38INDEX
39        snprintf
40INDEX
41        _snprintf_r
42INDEX
43        asnprintf
44INDEX
45        _asnprintf_r
46
47SYNOPSIS
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_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]>, ...);
70
71DESCRIPTION
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
535RETURNS
536On success, <<sprintf>> and <<asprintf>> return the number of bytes in
537the output string, except the concluding <<NUL>> is not counted.
538<<snprintf>> returns the number of bytes that would be in the output
539string, 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,
542otherwise it returns an allocated string.
543
544If 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
549to ENOMEM if allocation fails, and for <<snprintf>>, <<errno>> may be
550set to EOVERFLOW if <[size]> or the output length exceeds INT_MAX.
551
552BUGS
553The ``''' (quote) flag does not work when locale's thousands_sep is not empty.
554
555PORTABILITY
556ANSI C requires <<printf>>, <<fprintf>>, <<sprintf>>, and
557<<snprintf>>.  <<asprintf>> and <<asnprintf>> are newlib extensions.
558
559The ANSI C standard specifies that implementations must support at
560least formatted output of up to 509 characters.  This implementation
561has no inherent limit.
562
563Depending on how newlib was configured, not all format specifiers are
564supported.
565
566Supporting OS subroutines required: <<close>>, <<fstat>>, <<isatty>>,
567<<lseek>>, <<read>>, <<sbrk>>, <<write>>.
568*/
569
570#include <_ansi.h>
571#include <reent.h>
572#include <stdio.h>
573#include <stdarg.h>
574#include <limits.h>
575#include "local.h"
576
577int
578_sprintf_r (struct _reent *ptr,
579       char *__restrict str,
580       const char *__restrict fmt, ...)
581{
582  int ret;
583  va_list ap;
584  FILE f;
585
586  f._flags = __SWR | __SSTR;
587  f._bf._base = f._p = (unsigned char *) str;
588  f._bf._size = f._w = INT_MAX;
589  f._file = -1;  /* No file. */
590  va_start (ap, fmt);
591  ret = _svfprintf_r (ptr, &f, fmt, ap);
592  va_end (ap);
593  *f._p = '\0'; /* terminate the string */
594  return (ret);
595}
596
597#ifdef _NANO_FORMATTED_IO
598int
599_siprintf_r (struct _reent *, char *, const char *, ...)
600       _ATTRIBUTE ((__alias__("_sprintf_r")));
601#endif
602
603#ifndef _REENT_ONLY
604
605int
606sprintf (char *__restrict str,
607       const char *__restrict fmt, ...)
608{
609  int ret;
610  va_list ap;
611  FILE f;
612
613  f._flags = __SWR | __SSTR;
614  f._bf._base = f._p = (unsigned char *) str;
615  f._bf._size = f._w = INT_MAX;
616  f._file = -1;  /* No file. */
617  va_start (ap, fmt);
618  ret = _svfprintf_r (_REENT, &f, fmt, ap);
619  va_end (ap);
620  *f._p = '\0'; /* terminate the string */
621  return (ret);
622}
623
624#ifdef _NANO_FORMATTED_IO
625int
626siprintf (char *, const char *, ...)
627       _ATTRIBUTE ((__alias__("sprintf")));
628#endif
629#endif
Note: See TracBrowser for help on using the repository browser.