compiler/stdc/printf.c

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