compiler/clib/printf.c

   1 /*
   2     Copyright © 1995-2012, The AROS Development Team. All rights reserved.
   3     $Id$
   4
   5     C99 function printf().
   6 */
   7
   8 #include <stdarg.h>
   9
  10 /*****************************************************************************
  11
  12     NAME */
  13 #include <stdio.h>
  14
  15         int printf (
  16
  17 /*  SYNOPSIS */
  18         const char * format,
  19         ...)
  20
  21 /*  FUNCTION
  22         Formats a list of arguments and prints them to standard out.
  23
  24         The format string is composed of zero or more directives: ordinary
  25         characters (not %), which are copied unchanged to the output
  26         stream; and conversion specifications, each of which results in
  27         fetching zero or more subsequent arguments Each conversion
  28         specification is introduced by the character %. The arguments must
  29         correspond properly (after type promotion) with the conversion
  30         specifier. After the %, the following appear in sequence:
  31
  32         Zero or more of the following flags:
  33
  34         # - specifying that the value should be converted to an
  35             ``alternate form''. For c, d, i, n, p, s, and u conversions, this
  36             option has no effect. For o conversions, the precision of the
  37             number is increased to force the first character of the output
  38             string to a zero (except if a zero value is printed with an
  39             explicit precision of zero). For x and X conversions, a non-zero
  40             result has the string `0x' (or `0X' for X conversions) prepended to
  41             it. For e, E, f, g, and G conversions, the result will always
  42             contain a decimal point, even if no digits follow it (normally, a
  43             decimal point appears in the results of those conversions only if a
  44             digit follows). For g and G conversions, trailing zeros are not
  45             removed from the result as they would otherwise be.
  46
  47         0 - specifying zero padding. For all conversions except n, the
  48             converted value is padded on the left with zeros rather than
  49             blanks. If a precision is given with a numeric conversion (d, i, o,
  50             u, i, x, and X), the 0 flag is ignored.
  51
  52         - - (a negative field width flag) indicates the converted
  53             value is to be left adjusted on the field boundary. Except for n
  54             conversions, the converted value is padded on the right with
  55             blanks, rather than on the left with blanks or zeros. A -
  56             overrides a 0 if both are given.
  57
  58           - (a space) specifying that a blank should be left before a
  59             positive number produced by a signed conversion (d, e, E, f, g, G,
  60             or i). + specifying that a sign always be placed before a number
  61             produced by a signed conversion. A + overrides a space if both are
  62             used.
  63
  64         ' - specifying that in a numerical argument the output is to
  65             be grouped if the locale information indicates any. Note that many
  66             versions of gcc cannot parse this option and will issue a warning.
  67
  68         An optional decimal digit string specifying a minimum field
  69         width. If the converted value has fewer characters than the field
  70         width, it will be padded with spaces on the left (or right, if the
  71         left-adjustment flag has been given) to fill out the field width.
  72
  73         An optional precision, in the form of a period (`.') followed
  74         by an optional digit string. If the digit string is omitted, the
  75         precision is taken as zero. This gives the minimum number of digits
  76         to appear for d, i, o, u, x, and X conversions, the number of
  77         digits to appear after the decimal-point for e, E, and f
  78         conversions, the maximum number of significant digits for g and G
  79         conversions, or the maximum number of characters to be printed from
  80         a string for s conversions.
  81
  82         The optional character h, specifying that a following d, i,
  83         o, u, x, or X conversion corresponds to a short int or unsigned
  84         short int argument, or that a following n conversion corresponds to
  85         a pointer to a short int argument.
  86
  87         The optional character l (ell) specifying that a following d,
  88         i, o, u, x, or X conversion applies to a pointer to a long int or
  89         unsigned long int argument, or that a following n conversion
  90         corresponds to a pointer to a long int argument. Linux provides a
  91         non ANSI compliant use of two l flags as a synonym to q or L. Thus
  92         ll can be used in combination with float conversions. This usage
  93         is, however, strongly discouraged.
  94
  95         The character L specifying that a following e, E,
  96         f, g, or G conversion corresponds to a long double
  97         argument, or a following d, i, o, u, x, or X conversion corresponds to a long long argument. Note
  98         that long long is not specified in ANSI C and
  99         therefore not portable to all architectures.
 100
 101         The optional character q. This is equivalent to L. See the
 102         STANDARDS and BUGS sections for comments on the use of ll, L, and
 103         q.
 104
 105         A Z character specifying that the following integer (d, i, o,
 106         u, i, x, and X), conversion corresponds to a size_t argument.
 107
 108         A character that specifies the type of conversion to be
 109         applied.
 110
 111         A field width or precision, or both, may be indicated by an
 112         asterisk `*' instead of a digit string. In this case, an int
 113         argument supplies the field width or precision. A negative field
 114         width is treated as a left adjustment flag followed by a positive
 115         field width; a negative precision is treated as though it were
 116         missing.
 117
 118         The conversion specifiers and their meanings are:
 119
 120         diouxX - The int (or appropriate variant) argument is
 121                  converted to signed decimal (d and i), unsigned octal (o, unsigned
 122                  decimal (u, or unsigned hexadecimal (x and X) notation. The letters
 123                  abcdef are used for x conversions; the letters ABCDEF are used for
 124                  X conversions. The precision, if any, gives the minimum number of
 125                  digits that must appear; if the converted value requires fewer
 126                  digits, it is padded on the left with zeros.
 127
 128         eE - The double argument is rounded and converted in the style
 129              [<->]d.dddedd where there is one digit before the decimal-point
 130              character and the number of digits after it is equal to the
 131              precision; if the precision is missing, it is taken as 6; if the
 132              precision is zero, no decimal-point character appears. An E
 133              conversion uses the letter E (rather than e) to introduce the
 134              exponent. The exponent always contains at least two digits; if the
 135              value is zero, the exponent is 00.
 136
 137         f - The double argument is rounded and converted to decimal
 138             notation in the style [-]ddd.ddd, where the number of digits after
 139             the decimal-point character is equal to the precision
 140             specification. If the precision is missing, it is taken as 6; if
 141             the precision is explicitly zero, no decimal-point character
 142             appears. If a decimal point appears, at least one digit appears
 143             before it.
 144
 145         g - The double argument is converted in style f or e (or E for
 146             G conversions). The precision specifies the number of significant
 147             digits. If the precision is missing, 6 digits are given; if the
 148             precision is zero, it is treated as 1. Style e is used if the
 149             exponent from its conversion is less than -4 or greater than or
 150             equal to the precision. Trailing zeros are removed from the
 151             fractional part of the result; a decimal point appears only if it
 152             is followed by at least one digit.
 153
 154         c - The int argument is converted to an unsigned char, and the
 155             resulting character is written.
 156
 157         s - The ``char *'' argument is expected to be a pointer to an
 158             array of character type (pointer to a string). Characters from the
 159             array are written up to (but not including) a terminating NUL
 160             character; if a precision is specified, no more than the number
 161             specified are written. If a precision is given, no null character
 162             need be present; if the precision is not specified, or is greater
 163             than the size of the array, the array must contain a terminating
 164             NUL character.
 165
 166         p - The ``void *'' pointer argument is printed in hexadecimal
 167             (as if by %#x or %#lx).
 168
 169         n - The number of characters written so far is stored into the
 170             integer indicated by the ``int *'' (or variant) pointer argument.
 171             No argument is converted.
 172
 173         % - A `%' is written. No argument is converted. The complete
 174             conversion specification is `%%'.
 175
 176         In no case does a non-existent or small field width cause
 177         truncation of a field; if the result of a conversion is wider than
 178         the field width, the field is expanded to contain the conversion
 179         result.
 180
 181     INPUTS
 182         format - Format string as described above
 183         ... - Arguments for the format string
 184
 185     RESULT
 186         The number of characters written to stdout or EOF on error.
 187
 188     NOTES
 189
 190     EXAMPLE
 191         To print a date and time in the form `Sunday, July 3,
 192         10:02', where weekday and month are pointers to strings:
 193
 194             #include <stdio.h>
 195
 196             fprintf (stdout, "%s, %s %d, %.2d:%.2d\n",
 197                     weekday, month, day, hour, min);
 198
 199         To print to five decimal places:
 200
 201             #include <math.h>
 202             #include <stdio.h>
 203
 204             fprintf (stdout, "pi = %.5f\n", 4 * atan(1.0));
 205
 206         To allocate a 128 byte string and print into it:
 207
 208             #include <stdio.h>
 209             #include <stdlib.h>
 210             #include <stdarg.h>
 211
 212             char *newfmt(const char *fmt, ...)
 213             {
 214                 char *p;
 215                 va_list ap;
 216
 217                 if ((p = malloc(128)) == NULL)
 218                     return (NULL);
 219
 220                 va_start(ap, fmt);
 221
 222                 (void) vsnprintf(p, 128, fmt, ap);
 223
 224                 va_end(ap);
 225
 226                 return (p);
 227             }
 228
 229     BUGS
 230         All functions are fully ANSI C3.159-1989 conformant, but provide
 231         the additional flags q, Z and ' as well as an additional behaviour
 232         of the L and l flags. The latter may be considered to be a bug, as
 233         it changes the behaviour of flags defined in ANSI C3.159-1989.
 234
 235         The effect of padding the %p format with zeros (either by the 0
 236         flag or by specifying a precision), and the benign effect (i.e.,
 237         none) of the # flag on %n and %p conversions, as well as
 238         nonsensical combinations such as are not standard; such
 239         combinations should be avoided.
 240
 241         Some combinations of flags defined by ANSI C are not making sense
 242         in ANSI C (e.g. %Ld). While they may have a well-defined behaviour
 243         on Linux, this need not to be so on other architectures. Therefore
 244         it usually is better to use flags that are not defined by ANSI C at
 245         all, i.e. use q instead of L in combination with diouxX conversions
 246         or ll. The usage of q is not the same as on BSD 4.4, as it may be
 247         used in float conversions equivalently to L.
 248
 249         Because sprintf and vsprintf assume an infinitely long string,
 250         callers must be careful not to overflow the actual space; this is
 251         often impossible to assure.
 252
 253     SEE ALSO
 254         fprintf(), vprintf(), vfprintf(), sprintf(), vsprintf(),
 255         vsnprintf()
 256
 257     INTERNALS
 258
 259 ******************************************************************************/
 260 {
 261     int     retval;
 262     va_list args;
 263
 264     va_start (args, format);
 265
 266     retval = vfprintf (stdout, format, args);
 267
 268     va_end (args);
 269
 270     fflush (stdout);
 271
 272     return retval;
 273 } /* printf */
 274