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