stdio-common/printf.h

   1 /* Copyright (C) 1991-1993,1995-2001,2006,2009,2012
   2         Free Software Foundation, Inc.
   3    This file is part of the GNU C Library.
   4
   5    The GNU C Library is free software; you can redistribute it and/or
   6    modify it under the terms of the GNU Lesser General Public
   7    License as published by the Free Software Foundation; either
   8    version 2.1 of the License, or (at your option) any later version.
   9
  10    The GNU C Library is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13    Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser General Public
  16    License along with the GNU C Library; if not, see
  17    <http://www.gnu.org/licenses/>.  */
  18
  19 #ifndef _PRINTF_H
  20
  21 #define _PRINTF_H       1
  22 #include <features.h>
  23
  24 __BEGIN_DECLS
  25
  26 #define __need_FILE
  27 #include <stdio.h>
  28 #define __need_size_t
  29 #define __need_wchar_t
  30 #include <stddef.h>
  31 #include <stdarg.h>
  32
  33
  34 struct printf_info
  35 {
  36   int prec;                     /* Precision.  */
  37   int width;                    /* Width.  */
  38   wchar_t spec;                 /* Format letter.  */
  39   unsigned int is_long_double:1;/* L flag.  */
  40   unsigned int is_short:1;      /* h flag.  */
  41   unsigned int is_long:1;       /* l flag.  */
  42   unsigned int alt:1;           /* # flag.  */
  43   unsigned int space:1;         /* Space flag.  */
  44   unsigned int left:1;          /* - flag.  */
  45   unsigned int showsign:1;      /* + flag.  */
  46   unsigned int group:1;         /* ' flag.  */
  47   unsigned int extra:1;         /* For special use.  */
  48   unsigned int is_char:1;       /* hh flag.  */
  49   unsigned int wide:1;          /* Nonzero for wide character streams.  */
  50   unsigned int i18n:1;          /* I flag.  */
  51   unsigned int __pad:4;         /* Unused so far.  */
  52   unsigned short int user;      /* Bits for user-installed modifiers.  */
  53   wchar_t pad;                  /* Padding character.  */
  54 };
  55
  56
  57 /* Type of a printf specifier-handler function.
  58    STREAM is the FILE on which to write output.
  59    INFO gives information about the format specification.
  60    ARGS is a vector of pointers to the argument data;
  61    the number of pointers will be the number returned
  62    by the associated arginfo function for the same INFO.
  63
  64    The function should return the number of characters written,
  65    or -1 for errors.  */
  66
  67 typedef int printf_function (FILE *__stream,
  68                              const struct printf_info *__info,
  69                              const void *const *__args);
  70
  71 /* Type of a printf specifier-arginfo function.
  72    INFO gives information about the format specification.
  73    N, ARGTYPES, *SIZE has to contain the size of the parameter for
  74    user-defined types, and return value are as for parse_printf_format
  75    except that -1 should be returned if the handler cannot handle
  76    this case.  This allows to partially overwrite the functionality
  77    of existing format specifiers.  */
  78
  79 typedef int printf_arginfo_size_function (const struct printf_info *__info,
  80                                           size_t __n, int *__argtypes,
  81                                           int *__size);
  82
  83 /* Old version of 'printf_arginfo_function' without a SIZE parameter.  */
  84
  85 typedef int printf_arginfo_function (const struct printf_info *__info,
  86                                      size_t __n, int *__argtypes);
  87
  88 /* Type of a function to get a value of a user-defined from the
  89    variable argument list.  */
  90 typedef void printf_va_arg_function (void *__mem, va_list *__ap);
  91
  92
  93 /* Register FUNC to be called to format SPEC specifiers; ARGINFO must be
  94    specified to determine how many arguments a SPEC conversion requires and
  95    what their types are.  */
  96
  97 extern int register_printf_specifier (int __spec, printf_function __func,
  98                                       printf_arginfo_size_function __arginfo)
  99   __THROW;
 100
 101
 102 /* Obsolete interface similar to register_printf_specifier.  It can only
 103    handle basic data types because the ARGINFO callback does not return
 104    information on the size of the user-defined type.  */
 105
 106 extern int register_printf_function (int __spec, printf_function __func,
 107                                      printf_arginfo_function __arginfo)
 108   __THROW __attribute_deprecated__;
 109
 110
 111 /* Register a new modifier character sequence.  If the call succeeds
 112    it returns a positive value representing the bit set in the USER
 113    field in 'struct printf_info'.  */
 114
 115 extern int register_printf_modifier (const wchar_t *__str) __wur __THROW;
 116
 117
 118 /* Register variable argument handler for user type.  The return value
 119    is to be used in ARGINFO functions to signal the use of the
 120    type.  */
 121 extern int register_printf_type (printf_va_arg_function __fct) __wur __THROW;
 122
 123
 124 /* Parse FMT, and fill in N elements of ARGTYPES with the
 125    types needed for the conversions FMT specifies.  Returns
 126    the number of arguments required by FMT.
 127
 128    The ARGINFO function registered with a user-defined format is passed a
 129    `struct printf_info' describing the format spec being parsed.  A width
 130    or precision of INT_MIN means a `*' was used to indicate that the
 131    width/precision will come from an arg.  The function should fill in the
 132    array it is passed with the types of the arguments it wants, and return
 133    the number of arguments it wants.  */
 134
 135 extern size_t parse_printf_format (const char *__restrict __fmt, size_t __n,
 136                                    int *__restrict __argtypes) __THROW;
 137
 138
 139 /* Codes returned by `parse_printf_format' for basic types.
 140
 141    These values cover all the standard format specifications.
 142    Users can reserve new values after PA_LAST for their own types
 143    using 'register_printf_type'.  */
 144
 145 enum
 146 {                               /* C type: */
 147   PA_INT,                       /* int */
 148   PA_CHAR,                      /* int, cast to char */
 149   PA_WCHAR,                     /* wide char */
 150   PA_STRING,                    /* const char *, a '\0'-terminated string */
 151   PA_WSTRING,                   /* const wchar_t *, wide character string */
 152   PA_POINTER,                   /* void * */
 153   PA_FLOAT,                     /* float */
 154   PA_DOUBLE,                    /* double */
 155   PA_LAST
 156 };
 157
 158 /* Flag bits that can be set in a type returned by `parse_printf_format'.  */
 159 #define PA_FLAG_MASK            0xff00
 160 #define PA_FLAG_LONG_LONG       (1 << 8)
 161 #define PA_FLAG_LONG_DOUBLE     PA_FLAG_LONG_LONG
 162 #define PA_FLAG_LONG            (1 << 9)
 163 #define PA_FLAG_SHORT           (1 << 10)
 164 #define PA_FLAG_PTR             (1 << 11)
 165
 166
 167
 168 /* Function which can be registered as `printf'-handlers.  */
 169
 170 /* Print floating point value using using abbreviations for the orders
 171    of magnitude used for numbers ('k' for kilo, 'm' for mega etc).  If
 172    the format specifier is a uppercase character powers of 1000 are
 173    used.  Otherwise powers of 1024.  */
 174 extern int printf_size (FILE *__restrict __fp,
 175                         const struct printf_info *__info,
 176                         const void *const *__restrict __args) __THROW;
 177
 178 /* This is the appropriate argument information function for `printf_size'.  */
 179 extern int printf_size_info (const struct printf_info *__restrict
 180                              __info, size_t __n, int *__restrict __argtypes)
 181      __THROW;
 182
 183 #ifdef __LDBL_COMPAT
 184 # include <bits/printf-ldbl.h>
 185 #endif
 186
 187 __END_DECLS
 188
 189 #endif /* printf.h  */