compiler/posixc/printf.c

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