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 a,A,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, 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. For f,F conversion, or if a precision is given with a numeric
  52             conversion (d, i, o,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         aA - (TODO) The double argument is rounded and converted to the C99
 131               floating-point number in hexadecimal notation - preserving all
 132               bits of precision, and presenting them in a robust way.
 133
 134         eE - The double argument is rounded and converted in the style
 135              [<->]d.dddedd where there is one digit before the decimal-point
 136              character and the number of digits after it is equal to the
 137              precision; if the precision is missing, it is taken as 6; if the
 138              precision is zero, no decimal-point character appears. An E
 139              conversion uses the letter E (rather than e) to introduce the
 140              exponent. The exponent always contains at least two digits; if the
 141              value is zero, the exponent is 00.
 142
 143         fF - The double argument is rounded and converted to decimal
 144             notation in the style [-]ddd.ddd, where the number of digits after
 145             the decimal-point character is equal to the precision
 146             specification. If the precision is missing, it is taken as 6; if
 147             the precision is explicitly zero, no decimal-point character
 148             appears. If a decimal point appears, at least one digit appears
 149             before it.
 150
 151         g - The double argument is converted in style f or e (or E for
 152             G conversions). The precision specifies the number of significant
 153             digits. If the precision is missing, 6 digits are given; if the
 154             precision is zero, it is treated as 1. Style e is used if the
 155             exponent from its conversion is less than -4 or greater than or
 156             equal to the precision. Trailing zeros are removed from the
 157             fractional part of the result; a decimal point appears only if it
 158             is followed by at least one digit.
 159
 160         c - The int argument is converted to an unsigned char, and the
 161             resulting character is written.
 162
 163         s - The ``char *'' argument is expected to be a pointer to an
 164             array of character type (pointer to a string). Characters from the
 165             array are written up to (but not including) a terminating NUL
 166             character; if a precision is specified, no more than the number
 167             specified are written. If a precision is given, no null character
 168             need be present; if the precision is not specified, or is greater
 169             than the size of the array, the array must contain a terminating
 170             NUL character.
 171
 172         p - The ``void *'' pointer argument is printed in hexadecimal
 173             (as if by %#x or %#lx).
 174
 175         n - The number of characters written so far is stored into the
 176             integer indicated by the ``int *'' (or variant) pointer argument.
 177             No argument is converted.
 178
 179         % - A `%' is written. No argument is converted. The complete
 180             conversion specification is `%%'.
 181
 182         In no case does a non-existent or small field width cause
 183         truncation of a field; if the result of a conversion is wider than
 184         the field width, the field is expanded to contain the conversion
 185         result.
 186
 187     INPUTS
 188         format - Format string as described above
 189         ... - Arguments for the format string
 190
 191     RESULT
 192         The number of characters written to stdout or EOF on error.
 193
 194     NOTES
 195
 196     EXAMPLE
 197         To print a date and time in the form `Sunday, July 3,
 198         10:02', where weekday and month are pointers to strings:
 199
 200             #include <stdio.h>
 201
 202             fprintf (stdout, "%s, %s %d, %.2d:%.2d\n",
 203                     weekday, month, day, hour, min);
 204
 205         To print to five decimal places:
 206
 207             #include <math.h>
 208             #include <stdio.h>
 209
 210             fprintf (stdout, "pi = %.5f\n", 4 * atan(1.0));
 211
 212         To allocate a 128 byte string and print into it:
 213
 214             #include <stdio.h>
 215             #include <stdlib.h>
 216             #include <stdarg.h>
 217
 218             char *newfmt(const char *fmt, ...)
 219             {
 220                 char *p;
 221                 va_list ap;
 222
 223                 if ((p = malloc(128)) == NULL)
 224                     return (NULL);
 225
 226                 va_start(ap, fmt);
 227
 228                 (void) vsnprintf(p, 128, fmt, ap);
 229
 230                 va_end(ap);
 231
 232                 return (p);
 233             }
 234
 235     BUGS
 236         All functions are fully ANSI C3.159-1989 conformant, but provide
 237         the additional flags q, Z and ' as well as an additional behaviour
 238         of the L and l flags. The latter may be considered to be a bug, as
 239         it changes the behaviour of flags defined in ANSI C3.159-1989.
 240
 241         The effect of padding the %p format with zeros (either by the 0
 242         flag or by specifying a precision), and the benign effect (i.e.,
 243         none) of the # flag on %n and %p conversions, as well as
 244         nonsensical combinations such as are not standard; such
 245         combinations should be avoided.
 246
 247         Some combinations of flags defined by ANSI C are not making sense
 248         in ANSI C (e.g. %Ld). While they may have a well-defined behaviour
 249         on Linux, this need not to be so on other architectures. Therefore
 250         it usually is better to use flags that are not defined by ANSI C at
 251         all, i.e. use q instead of L in combination with diouxX conversions
 252         or ll. The usage of q is not the same as on BSD 4.4, as it may be
 253         used in float conversions equivalently to L.
 254
 255         Because sprintf and vsprintf assume an infinitely long string,
 256         callers must be careful not to overflow the actual space; this is
 257         often impossible to assure.
 258
 259     SEE ALSO
 260         fprintf(), vprintf(), vfprintf(), stdc.library/sprintf(),
 261         stdc.library/vsprintf(), stdc.library/vsnprintf()
 262
 263     INTERNALS
 264
 265 ******************************************************************************/
 266 {
 267     struct PosixCBase *PosixCBase = __aros_getbase_PosixCBase();
 268     int     retval;
 269     va_list args;
 270
 271     va_start (args, format);
 272
 273     retval = vfprintf (PosixCBase->_stdout, format, args);
 274
 275     va_end (args);
 276
 277     fflush (PosixCBase->_stdout);
 278
 279     return retval;
 280 } /* printf */
 281