toolchain/gcc/newlib/libc/stdio/sprintf.c

   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 /*
  19
  20 FUNCTION
  21         <<printf>>, <<fprintf>>, <<asprintf>>, <<sprintf>>, <<snprintf>>---format output
  22 INDEX
  23         fprintf
  24 INDEX
  25         printf
  26 INDEX
  27         asprintf
  28 INDEX
  29         sprintf
  30 INDEX
  31         snprintf
  32
  33 ANSI_SYNOPSIS
  34         #include <stdio.h>
  35
  36         int printf(const char *<[format]> [, <[arg]>, ...]);
  37         int fprintf(FILE *<[fd]>, const char *<[format]> [, <[arg]>, ...]);
  38         int sprintf(char *<[str]>, const char *<[format]> [, <[arg]>, ...]);
  39         int asprintf(char **<[strp]>, const char *<[format]> [, <[arg]>, ...]);
  40         int snprintf(char *<[str]>, size_t <[size]>, const char *<[format]> [, <[arg]>, ...]);
  41
  42 TRAD_SYNOPSIS
  43         #include <stdio.h>
  44
  45         int printf(<[format]> [, <[arg]>, ...])
  46         char *<[format]>;
  47
  48         int fprintf(<[fd]>, <[format]> [, <[arg]>, ...]);
  49         FILE *<[fd]>;
  50         char *<[format]>;
  51
  52         int asprintf(<[strp]>, <[format]> [, <[arg]>, ...]);
  53         char **<[strp]>;
  54         char *<[format]>;
  55
  56         int sprintf(<[str]>, <[format]> [, <[arg]>, ...]);
  57         char *<[str]>;
  58         char *<[format]>;
  59
  60         int snprintf(<[str]>, size_t <[size]>, <[format]> [, <[arg]>, ...]);
  61         char *<[str]>;
  62         size_t <[size]>;
  63         char *<[format]>;
  64
  65 DESCRIPTION
  66         <<printf>> accepts a series of arguments, applies to each a
  67         format specifier from <<*<[format]>>>, and writes the
  68         formatted data to <<stdout>>, terminated with a null character.
  69         The behavior of <<printf>> is undefined if there are not enough
  70         arguments for the format.
  71         <<printf>> returns when it reaches the end of the format string.
  72         If there are more arguments than the format requires, excess
  73         arguments are ignored.
  74
  75         <<fprintf>>, <<asprintf>>, <<sprintf>> and <<snprintf>> are identical
  76         to <<printf>>, other than the destination of the formatted output:
  77         <<fprintf>> sends the output to a specified file <[fd]>, while
  78         <<asprintf>> stores the output in a dynamically allocated buffer,
  79         while <<sprintf>> stores the output in the specified char array
  80         <[str]> and <<snprintf>> limits number of characters written to
  81         <[str]> to at most <[size]> (including terminating <<0>>).  For
  82         <<sprintf>> and <<snprintf>>, the behavior is undefined if the
  83         output <<*<[str]>>> overlaps with one of the arguments. For
  84         <<asprintf>>, <[strp]> points to a pointer to char which is filled
  85         in with the dynamically allocated buffer.  <[format]> is a pointer
  86         to a charater string containing two types of objects: ordinary
  87         characters (other than <<%>>), which are copied unchanged to the
  88         output, and conversion specifications, each of which is introduced
  89         by <<%>>. (To include <<%>> in the output, use <<%%>> in the format
  90         string.) A conversion specification has the following form:
  91
  92 .       %[<[flags]>][<[width]>][.<[prec]>][<[size]>][<[type]>]
  93
  94         The fields of the conversion specification have the following meanings:
  95
  96         O+
  97         o <[flags]>
  98
  99         an optional sequence of characters which control
 100         output justification, numeric signs, decimal points,
 101         trailing zeroes, and octal and hex prefixes.
 102         The flag characters are minus (<<->>), plus (<<+>>),
 103         space ( ), zero (<<0>>), and sharp (<<#>>).  They can
 104         appear in any combination.
 105
 106         o+
 107         o -
 108                 The result of the conversion is left justified, and the right is
 109                 padded with blanks.  If you do not use this flag, the result is right
 110                 justified, and padded on the left.
 111
 112         o +
 113                 The result of a signed conversion (as determined by <[type]>)
 114                 will always begin with a plus or minus sign.  (If you do not use
 115         this flag, positive values do not begin with a plus sign.)
 116
 117         o " " (space)
 118                 If the first character of a signed conversion specification
 119         is not a sign, or if a signed conversion results in no
 120                 characters, the result will begin with a space.  If the
 121         space ( ) flag and the plus (<<+>>) flag both appear,
 122                 the space flag is ignored.
 123
 124         o 0
 125                 If the <[type]> character is <<d>>, <<i>>, <<o>>, <<u>>,
 126                 <<x>>, <<X>>, <<e>>, <<E>>, <<f>>, <<g>>, or <<G>>: leading zeroes,
 127                 are used to pad the field width (following any indication of sign or
 128                 base); no spaces are used for padding.  If the zero (<<0>>) and
 129                 minus (<<->>) flags both appear, the zero (<<0>>) flag will
 130                 be ignored.  For <<d>>, <<i>>, <<o>>, <<u>>, <<x>>, and <<X>>
 131                 conversions, if a precision <[prec]> is specified, the zero (<<0>>)
 132         flag is ignored.
 133
 134                 Note that <<0>> is interpreted as a flag, not as the beginning
 135         of a field width.
 136
 137         o #
 138                 The result is to be converted to an alternative form, according
 139                 to the next character:
 140
 141             o+
 142                     o 0
 143                         increases precision to force the first digit
 144                         of the result to be a zero.
 145
 146                         o x
 147                         a non-zero result will have a <<0x>> prefix.
 148
 149                         o X
 150                         a non-zero result will have a <<0X>> prefix.
 151
 152                         o e, E or f
 153                         The result will always contain a decimal point
 154                         even if no digits follow the point.
 155                         (Normally, a decimal point appears only if a
 156                         digit follows it.)  Trailing zeroes are removed.
 157
 158                         o g or G
 159                         same as <<e>> or <<E>>, but trailing zeroes
 160                         are not removed.
 161
 162                         o all others
 163                         undefined.
 164
 165                         o-
 166       o-
 167
 168       o <[width]>
 169
 170           <[width]> is an optional minimum field width.  You can either
 171           specify it directly as a decimal integer, or indirectly by
 172           using instead an asterisk (<<*>>), in which case an <<int>>
 173           argument is used as the field width.  Negative field widths
 174           are not supported; if you attempt to specify a negative field
 175           width, it is interpreted as a minus (<<->>) flag followed by a
 176           positive field width.
 177
 178       o <[prec]>
 179
 180           an optional field; if present, it is introduced with `<<.>>'
 181           (a period). This field gives the maximum number of
 182           characters to print in a conversion; the minimum number of
 183           digits of an integer to print, for conversions with <[type]>
 184           <<d>>, <<i>>, <<o>>, <<u>>, <<x>>, and <<X>>; the maximum number of
 185           significant digits, for the <<g>> and <<G>> conversions;
 186           or the number of digits to print after the decimal
 187           point, for <<e>>, <<E>>, and <<f>> conversions.  You can specify
 188           the precision either directly as a decimal integer or
 189           indirectly by using an asterisk (<<*>>), in which case
 190           an <<int>> argument is used as the precision.  Supplying a negative
 191       precision is equivalent to omitting the precision.
 192           If only a period is specified the precision is zero.
 193           If a precision appears with any other conversion <[type]>
 194           than those listed here, the behavior is undefined.
 195
 196       o  <[size]>
 197
 198                 <<h>>, <<l>>, and <<L>> are optional size characters which
 199                 override the default way that <<printf>> interprets the
 200                 data type of the corresponding argument.  <<h>> forces
 201                 the following <<d>>, <<i>>, <<o>>, <<u>>, <<x>> or <<X>> conversion
 202                 <[type]> to apply to a <<short>> or <<unsigned short>>. <<h>> also
 203                 forces a following <<n>> <[type]> to apply to
 204                 a pointer to a <<short>>. Similarily, an
 205                 <<l>> forces the following <<d>>, <<i>>, <<o>>, <<u>>,
 206                 <<x>> or <<X>> conversion <[type]> to apply to a <<long>> or
 207                 <<unsigned long>>.  <<l>> also forces a following <<n>> <[type]> to
 208                 apply to a pointer to a <<long>>.  <<l>> with <<c>>, <<s>> is
 209                 equivalent to <<C>>, <<S>> respectively.  If an <<h>>
 210                 or an <<l>> appears with another conversion
 211                 specifier, the behavior is undefined.  <<L>> forces a
 212                 following <<e>>, <<E>>, <<f>>, <<g>> or <<G>> conversion <[type]> to
 213                 apply to a <<long double>> argument.  If <<L>> appears with
 214                 any other conversion <[type]>, the behavior is undefined.
 215
 216      o   <[type]>
 217
 218                 <[type]> specifies what kind of conversion <<printf>> performs.
 219                 Here is a table of these:
 220
 221         o+
 222                 o %
 223                 prints the percent character (<<%>>)
 224
 225                 o c
 226                 prints <[arg]> as single character
 227
 228                 o C
 229                 prints wchar_t <[arg]> as single multibyte character
 230
 231                 o s
 232                 prints characters until precision is reached or a null terminator
 233                 is encountered; takes a string pointer
 234
 235                 o S
 236                 converts wchar_t characters to multibyte output characters until
 237                 precision is reached or a null wchar_t terminator
 238                 is encountered; takes a wchar_t pointer
 239
 240                 o d
 241                 prints a signed decimal integer; takes an <<int>> (same as <<i>>)
 242
 243                 o i
 244                 prints a signed decimal integer; takes an <<int>> (same as <<d>>)
 245
 246                 o o
 247                 prints a signed octal integer; takes an <<int>>
 248
 249                 o u
 250                 prints an unsigned decimal integer; takes an <<int>>
 251
 252                 o x
 253                 prints an unsigned hexadecimal integer (using <<abcdef>> as
 254                 digits beyond <<9>>); takes an <<int>>
 255
 256                 o X
 257                 prints an unsigned hexadecimal integer (using <<ABCDEF>> as
 258                 digits beyond <<9>>); takes an <<int>>
 259
 260                 o f
 261                 prints a signed value of the form <<[-]9999.9999>>; takes
 262                 a floating-point number
 263
 264                 o e
 265                 prints a signed value of the form <<[-]9.9999e[+|-]999>>; takes a
 266                 floating-point number
 267
 268                 o E
 269                 prints the same way as <<e>>, but using <<E>> to introduce the
 270                 exponent; takes a floating-point number
 271
 272                 o g
 273                 prints a signed value in either <<f>> or <<e>> form, based on given
 274                 value and precision---trailing zeros and the decimal point are
 275                 printed only if necessary; takes a floating-point number
 276
 277                 o G
 278                 prints the same way as <<g>>, but using <<E>> for the exponent if an
 279                 exponent is needed; takes a floating-point number
 280
 281                 o n
 282                 stores (in the same object) a count of the characters written;
 283                 takes a pointer to <<int>>
 284
 285                 o p
 286                 prints a pointer in an implementation-defined format.
 287                 This implementation treats the pointer as an
 288                 <<unsigned long>> (same as <<Lu>>).
 289         o-
 290 O-
 291
 292
 293 RETURNS
 294 <<sprintf>> and <<asprintf>> return the number of bytes in the output string,
 295 save that the concluding <<NULL>> is not counted.
 296 <<printf>> and <<fprintf>> return the number of characters transmitted.
 297 If an error occurs, <<printf>> and <<fprintf>> return <<EOF>> and
 298 <<asprintf>> returns -1.  No error returns occur for <<sprintf>>.
 299
 300 PORTABILITY
 301         The  ANSI C standard specifies that implementations must
 302         support at least formatted output of up to 509 characters.
 303
 304 Supporting OS subroutines required: <<close>>, <<fstat>>, <<isatty>>,
 305 <<lseek>>, <<read>>, <<sbrk>>, <<write>>.
 306 */
 307
 308 #include <stdio.h>
 309 #ifdef _HAVE_STDC
 310 #include <stdarg.h>
 311 #else
 312 #include <varargs.h>
 313 #endif
 314 #include <limits.h>
 315 #include <_ansi.h>
 316 #include "local.h"
 317
 318 int
 319 #ifdef _HAVE_STDC
 320 _DEFUN (_sprintf_r, (ptr, str, fmt), struct _reent *ptr _AND char *str _AND _CONST char *fmt _DOTS)
 321 #else
 322 _sprintf_r (ptr, str, fmt, va_alist)
 323      struct _reent *ptr;
 324      char *str;
 325      _CONST char *fmt;
 326      va_dcl
 327 #endif
 328 {
 329   int ret;
 330   va_list ap;
 331   FILE f;
 332
 333   f._flags = __SWR | __SSTR;
 334   f._bf._base = f._p = (unsigned char *) str;
 335   f._bf._size = f._w = INT_MAX;
 336   f._file = -1;  /* No file. */
 337 #ifdef _HAVE_STDC
 338   va_start (ap, fmt);
 339 #else
 340   va_start (ap);
 341 #endif
 342   ret = _vfprintf_r (ptr, &f, fmt, ap);
 343   va_end (ap);
 344   *f._p = 0;
 345   return (ret);
 346 }
 347
 348 #ifndef _REENT_ONLY
 349
 350 int
 351 #ifdef _HAVE_STDC
 352 _DEFUN (sprintf, (str, fmt), char *str _AND _CONST char *fmt _DOTS)
 353 #else
 354 sprintf (str, fmt, va_alist)
 355      char *str;
 356      _CONST char *fmt;
 357      va_dcl
 358 #endif
 359 {
 360   int ret;
 361   va_list ap;
 362   FILE f;
 363
 364   f._flags = __SWR | __SSTR;
 365   f._bf._base = f._p = (unsigned char *) str;
 366   f._bf._size = f._w = INT_MAX;
 367   f._file = -1;  /* No file. */
 368 #ifdef _HAVE_STDC
 369   va_start (ap, fmt);
 370 #else
 371   va_start (ap);
 372 #endif
 373   ret = _vfprintf_r (_REENT, &f, fmt, ap);
 374   va_end (ap);
 375   *f._p = 0;
 376   return (ret);
 377 }
 378
 379 #endif