compiler/clib/printf.c

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