[thirdparty/glibc.git] / stdio-common / printf.h

/* Copyright (C) 1991-2015 Free Software Foundation, Inc.
   This file is part of the GNU C Library.

   The GNU C Library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Lesser General Public
   License as published by the Free Software Foundation; either
   version 2.1 of the License, or (at your option) any later version.

   The GNU C Library is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
   Lesser General Public License for more details.

   You should have received a copy of the GNU Lesser General Public
   License along with the GNU C Library; if not, see
   <http://www.gnu.org/licenses/>.  */

#ifndef	_PRINTF_H

#define	_PRINTF_H	1
#include <features.h>

__BEGIN_DECLS

#define	__need_FILE
#include <stdio.h>
#define	__need_size_t
#define __need_wchar_t
#include <stddef.h>
#include <stdarg.h>


struct printf_info
{
  int prec;			/* Precision.  */
  int width;			/* Width.  */
  wchar_t spec;			/* Format letter.  */
  unsigned int is_long_double:1;/* L flag.  */
  unsigned int is_short:1;	/* h flag.  */
  unsigned int is_long:1;	/* l flag.  */
  unsigned int alt:1;		/* # flag.  */
  unsigned int space:1;		/* Space flag.  */
  unsigned int left:1;		/* - flag.  */
  unsigned int showsign:1;	/* + flag.  */
  unsigned int group:1;		/* ' flag.  */
  unsigned int extra:1;		/* For special use.  */
  unsigned int is_char:1;	/* hh flag.  */
  unsigned int wide:1;		/* Nonzero for wide character streams.  */
  unsigned int i18n:1;		/* I flag.  */
  unsigned int __pad:4;		/* Unused so far.  */
  unsigned short int user;	/* Bits for user-installed modifiers.  */
  wchar_t pad;			/* Padding character.  */
};


/* Type of a printf specifier-handler function.
   STREAM is the FILE on which to write output.
   INFO gives information about the format specification.
   ARGS is a vector of pointers to the argument data;
   the number of pointers will be the number returned
   by the associated arginfo function for the same INFO.

   The function should return the number of characters written,
   or -1 for errors.  */

typedef int printf_function (FILE *__stream,
			     const struct printf_info *__info,
			     const void *const *__args);

/* Type of a printf specifier-arginfo function.
   INFO gives information about the format specification.
   N, ARGTYPES, *SIZE has to contain the size of the parameter for
   user-defined types, and return value are as for parse_printf_format
   except that -1 should be returned if the handler cannot handle
   this case.  This allows to partially overwrite the functionality
   of existing format specifiers.  */

typedef int printf_arginfo_size_function (const struct printf_info *__info,
					  size_t __n, int *__argtypes,
					  int *__size);

/* Old version of 'printf_arginfo_function' without a SIZE parameter.  */

typedef int printf_arginfo_function (const struct printf_info *__info,
				     size_t __n, int *__argtypes);

/* Type of a function to get a value of a user-defined from the
   variable argument list.  */
typedef void printf_va_arg_function (void *__mem, va_list *__ap);


/* Register FUNC to be called to format SPEC specifiers; ARGINFO must be
   specified to determine how many arguments a SPEC conversion requires and
   what their types are.  */

extern int register_printf_specifier (int __spec, printf_function __func,
				      printf_arginfo_size_function __arginfo)
  __THROW;


/* Obsolete interface similar to register_printf_specifier.  It can only
   handle basic data types because the ARGINFO callback does not return
   information on the size of the user-defined type.  */

extern int register_printf_function (int __spec, printf_function __func,
				     printf_arginfo_function __arginfo)
  __THROW __attribute_deprecated__;


/* Register a new modifier character sequence.  If the call succeeds
   it returns a positive value representing the bit set in the USER
   field in 'struct printf_info'.  */

extern int register_printf_modifier (const wchar_t *__str) __wur __THROW;


/* Register variable argument handler for user type.  The return value
   is to be used in ARGINFO functions to signal the use of the
   type.  */
extern int register_printf_type (printf_va_arg_function __fct) __wur __THROW;


/* Parse FMT, and fill in N elements of ARGTYPES with the
   types needed for the conversions FMT specifies.  Returns
   the number of arguments required by FMT.

   The ARGINFO function registered with a user-defined format is passed a
   `struct printf_info' describing the format spec being parsed.  A width
   or precision of INT_MIN means a `*' was used to indicate that the
   width/precision will come from an arg.  The function should fill in the
   array it is passed with the types of the arguments it wants, and return
   the number of arguments it wants.  */

extern size_t parse_printf_format (const char *__restrict __fmt, size_t __n,
				   int *__restrict __argtypes) __THROW;


/* Codes returned by `parse_printf_format' for basic types.

   These values cover all the standard format specifications.
   Users can reserve new values after PA_LAST for their own types
   using 'register_printf_type'.  */

enum
{				/* C type: */
  PA_INT,			/* int */
  PA_CHAR,			/* int, cast to char */
  PA_WCHAR,			/* wide char */
  PA_STRING,			/* const char *, a '\0'-terminated string */
  PA_WSTRING,			/* const wchar_t *, wide character string */
  PA_POINTER,			/* void * */
  PA_FLOAT,			/* float */
  PA_DOUBLE,			/* double */
  PA_LAST
};

/* Flag bits that can be set in a type returned by `parse_printf_format'.  */
#define	PA_FLAG_MASK		0xff00
#define	PA_FLAG_LONG_LONG	(1 << 8)
#define	PA_FLAG_LONG_DOUBLE	PA_FLAG_LONG_LONG
#define	PA_FLAG_LONG		(1 << 9)
#define	PA_FLAG_SHORT		(1 << 10)
#define	PA_FLAG_PTR		(1 << 11)


/* Function which can be registered as `printf'-handlers.  */

/* Print floating point value using using abbreviations for the orders
   of magnitude used for numbers ('k' for kilo, 'm' for mega etc).  If
   the format specifier is a uppercase character powers of 1000 are
   used.  Otherwise powers of 1024.  */
extern int printf_size (FILE *__restrict __fp,
			const struct printf_info *__info,
			const void *const *__restrict __args) __THROW;

/* This is the appropriate argument information function for `printf_size'.  */
extern int printf_size_info (const struct printf_info *__restrict
			     __info, size_t __n, int *__restrict __argtypes)
     __THROW;

#ifdef __LDBL_COMPAT
# include <bits/printf-ldbl.h>
#endif

__END_DECLS

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