The functions described in this section (printf and related functions) provide a convenient way to perform formatted output. You call printf with a format string or template string that specifies how to format the values of the remaining arguments.
Unless your program is a filter that specifically performs line- or character-oriented processing, using printf or one of the other related functions described in this section is usually the easiest and most concise way to perform output. These functions are especially useful for printing error messages, tables of data, and the like.
The printf function can be used to print any number of arguments. The template string argument you supply in a call provides information not only about the number of additional arguments, but also about their types and what style should be used for printing them.
Ordinary characters in the template string are simply written to the output stream as-is, while conversion specifications introduced by a % character in the template cause subsequent arguments to be formatted and written to the output stream. For example,
int pct = 37; char filename[] = "foo.txt"; printf ("Processing of `%s' is %d%% finished.\nPlease be patient.\n", filename, pct);
produces output like
Processing of `foo.txt' is 37% finished. Please be patient.
This example shows the use of the %d conversion to specify that an int argument should be printed in decimal notation, the %s conversion to specify printing of a string argument, and the %% conversion to print a literal % character.
There are also conversions for printing an integer argument as an unsigned value in octal, decimal, or hexadecimal radix (%o, %u, or %x, respectively); or as a character value (%c).
Floating-point numbers can be printed in normal, fixed-point notation using the %f conversion or in exponential notation using the %e conversion. The %g conversion uses either %e or %f format, depending on what is more appropriate for the magnitude of the particular number.
You can control formatting more precisely by writing modifiers between the % and the character that indicates which conversion to apply. These slightly alter the ordinary behavior of the conversion. For example, most conversion specifications permit you to specify a minimum field width and a flag indicating whether you want the result left- or right-justified within the field.
The specific flags and modifiers that are permitted and their interpretation vary depending on the particular conversion. They're all described in more detail in the following sections. Don't worry if this all seems excessively complicated at first; you can almost always get reasonable free-format output without using any of the modifiers at all. The modifiers are mostly used to make the output look "prettier" in tables.
This section provides details about the precise syntax of conversion specifications that can appear in a printf template string.
Characters in the template string that are not part of a conversion specification are printed as-is to the output stream. Multibyte character sequences (Chapter 7) are permitted in a template string.
The conversion specifications in a printf template string have the general form:
% [ param-no $] flagswidth [ . precision ] typeconversion
For example, in the conversion specifier %-10.8ld, the - is a flag, 10 specifies the field width, the precision is 8, the letter l is a type modifier, and d specifies the conversion style. (This particular type specifier says to print a long int argument in decimal notation, with a minimum of 8 digits left-justified in a field at least 10 characters wide.)
In more detail, output conversion specifications consist of an initial % character followed in sequence by:
An optional specification of the parameter used for this format. Normally the parameters to the printf function are assigned to the formats in the order of appearance in the format string. But in some situations (such as message translation) this is not desirable and this extension allows an explicit parameter to be specified.
The param-no part of the format must be an integer in the range of 1 to the maximum number of arguments present to the function call. Some implementations limit this number to a certainly upper bound. The exact limit can be retrieved by the following constant.
function>NL_ARGMAX/function> The value of ARGMAX is the maximum value allowed for the specification of an positional parameter in a printf call. The actual value in effect at runtime can be retrieved by using sysconf using the _SC_NL_ARGMAX parameter the section called “Definition of sysconf”.
Some system have a quite low limit such as 9 for System V systems. The GNU C library has no real limit.
If any of the formats has a specification for the parameter position all of them in the format string shall have one. Otherwise the behavior is undefined.
Zero or more flag characters that modify the normal behavior of the conversion specification.
An optional decimal integer specifying the minimum field width. If the normal conversion produces fewer characters than this, the field is padded with spaces to the specified width. This is a minimum value; if the normal conversion produces more characters than this, the field is not truncated. Normally, the output is right-justified within the field. You can also specify a field width of *. This means that the next argument in the argument list (before the actual value to be printed) is used as the field width. The value must be an int. If the value is negative, this means to set the - flag (see below) and to use the absolute value as the field width.
An optional precision to specify the number of digits to be written for the numeric conversions. If the precision is specified, it consists of a period (.) followed optionally by a decimal integer (which defaults to zero if omitted). You can also specify a precision of *. This means that the next argument in the argument list (before the actual value to be printed) is used as the precision. The value must be an int, and is ignored if it is negative. If you specify * for both the field width and precision, the field width argument precedes the precision argument. Other C library versions may not recognize this syntax.
An optional type modifier character, which is used to specify the data type of the corresponding argument if it differs from the default type. (For example, the integer conversions assume a type of int, but you can specify h, l, or L for other integer types.)
A character that specifies the conversion to be applied.
The exact options that are permitted and how they are interpreted vary between the different conversion specifiers. See the descriptions of the individual conversions for information about the particular options that they use.
With the -Wformat option, the GNU C compiler checks calls to printf and related functions. It examines the format string and verifies that the correct number and types of arguments are supplied. There is also a GNU C syntax to tell the compiler that a function you write uses a printf-style format string. , for more information.
Here is a table summarizing what all the different conversions do:
Print an integer as a signed decimal number. the section called “Integer Conversions”, for details. %d and %i are synonymous for output, but are different when used with scanf for input (the section called “Table of Input Conversions”).
Print an integer as an unsigned octal number. the section called “Integer Conversions”, for details.
Print an integer as an unsigned decimal number. the section called “Integer Conversions”, for details.
Print an integer as an unsigned hexadecimal number. %x uses lower-case letters and %X uses upper-case. the section called “Integer Conversions”, for details.
Print a floating-point number in normal (fixed-point) notation. the section called “Floating-Point Conversions”, for details.
Print a floating-point number in exponential notation. %e uses lower-case letters and %E uses upper-case. the section called “Floating-Point Conversions”, for details.
Print a floating-point number in either normal or exponential notation, whichever is more appropriate for its magnitude. %g uses lower-case letters and %G uses upper-case. the section called “Floating-Point Conversions”, for details.
Print a floating-point number in a hexadecimal fractional notation which the exponent to base 2 represented in decimal digits. %a uses lower-case letters and %A uses upper-case. the section called “Floating-Point Conversions”, for details.
Print a single character. the section called “Other Output Conversions”.
This is an alias for %lc which is supported for compatibility with the Unix standard.
Print a string. the section called “Other Output Conversions”.
This is an alias for %ls which is supported for compatibility with the Unix standard.
Print the value of a pointer. the section called “Other Output Conversions”.
Get the number of characters printed so far. the section called “Other Output Conversions”. Note that this conversion specification never produces any output.
Print the string corresponding to the value of errno. (This is a GNU extension.) the section called “Other Output Conversions”.
Print a literal % character. the section called “Other Output Conversions”.
If the syntax of a conversion specification is invalid, unpredictable things will happen, so don't do this. If there aren't enough function arguments provided to supply values for all the conversion specifications in the template string, or if the arguments are not of the correct types, the results are unpredictable. If you supply more arguments than conversion specifications, the extra argument values are simply ignored; this is sometimes useful.
This section describes the options for the %d, %i, %o, %u, %x, and %X conversion specifications. These conversions print integers in various formats.
The %d and %i conversion specifications both print an int argument as a signed decimal number; while %o, %u, and %x print the argument as an unsigned octal, decimal, or hexadecimal number (respectively). The %X conversion specification is just like %x except that it uses the characters ABCDEF as digits instead of abcdef.
The following flags are meaningful:
Left-justify the result in the field (instead of the normal right-justification).
For the signed %d and %i conversions, print a plus sign if the value is positive.
For the signed %d and %i conversions, if the result doesn't start with a plus or minus sign, prefix it with a space character instead. Since the + flag ensures that the result includes a sign, this flag is ignored if you supply both of them.
For the %o conversion, this forces the leading digit to be 0, as if by increasing the precision. For %x or %X, this prefixes a leading 0x or 0X (respectively) to the result. This doesn't do anything useful for the %d, %i, or %u conversions. Using this flag produces output which can be parsed by the strtoul function (the section called “Parsing of Integers”) and scanf with the %i conversion (the section called “Numeric Input Conversions”).
Separate the digits into groups as specified by the locale specified for the LC_NUMERIC category; the section called “Generic Numeric Formatting Parameters”. This flag is a GNU extension.
Pad the field with zeros instead of spaces. The zeros are placed after any indication of sign or base. This flag is ignored if the - flag is also specified, or if a precision is specified.
If a precision is supplied, it specifies the minimum number of digits to appear; leading zeros are produced if necessary. If you don't specify a precision, the number is printed with as many digits as it needs. If you convert a value of zero with an explicit precision of zero, then no characters at all are produced.
Without a type modifier, the corresponding argument is treated as an int (for the signed conversions %i and %d) or unsigned int (for the unsigned conversions %o, %u, %x, and %X). Recall that since printf and friends are variadic, any char and short arguments are automatically converted to int by the default argument promotions. For arguments of other integer types, you can use these modifiers:
Specifies that the argument is a signed char or unsigned char, as appropriate. A char argument is converted to an int or unsigned int by the default argument promotions anyway, but the h modifier says to convert it back to a char again.
This modifier was introduced in ISO C99.
Specifies that the argument is a short int or unsigned short int, as appropriate. A short argument is converted to an int or unsigned int by the default argument promotions anyway, but the h modifier says to convert it back to a short again.
Specifies that the argument is a intmax_t or uintmax_t, as appropriate.
This modifier was introduced in ISO C99.
Specifies that the argument is a long int or unsigned long int, as appropriate. Two l characters is like the L modifier, below.
If used with %c or %s the corresponding parameter is considered as a wide character or wide character string respectively. This use of l was introduced in Amendment 1 to ISO C90.
Specifies that the argument is a long long int. (This type is an extension supported by the GNU C compiler. On systems that don't support extra-long integers, this is the same as long int.)
The q modifier is another name for the same thing, which comes from 4.4 BSD; a long long int is sometimes called a "quad" int.
Specifies that the argument is a ptrdiff_t.
This modifier was introduced in ISO C99.
Specifies that the argument is a size_t.
z was introduced in ISO C99. Z is a GNU extension predating this addition and should not be used in new code.
Here is an example. Using the template string:
"|%5d|%-5d|%+5d|%+-5d|% 5d|%05d|%5.0d|%5.2d|%d|\n"
to print numbers using the different options for the %d conversion gives results like:
| 0|0 | +0|+0 | 0|00000| | 00|0| | 1|1 | +1|+1 | 1|00001| 1| 01|1| | -1|-1 | -1|-1 | -1|-0001| -1| -01|-1| |100000|100000|+100000| 100000|100000|100000|100000|100000|
In particular, notice what happens in the last case where the number is too large to fit in the minimum field width specified.
Here are some more examples showing how unsigned integers print under various format options, using the template string:
"|%5u|%5o|%5x|%5X|%#5o|%#5x|%#5X|%#10.8x|\n"
| 0| 0| 0| 0| 0| 0x0| 0X0|0x00000000| | 1| 1| 1| 1| 01| 0x1| 0X1|0x00000001| |100000|303240|186a0|186A0|0303240|0x186a0|0X186A0|0x000186a0|
This section discusses the conversion specifications for floating-point numbers: the %f, %e, %E, %g, and %G conversions.
The %f conversion prints its argument in fixed-point notation, producing output of the form [-]ddd.ddd, where the number of digits following the decimal point is controlled by the precision you specify.
The %e conversion prints its argument in exponential notation, producing output of the form [-]d.ddde[+|-]dd. Again, the number of digits following the decimal point is controlled by the precision. The exponent always contains at least two digits. The %E conversion is similar but the exponent is marked with the letter E instead of e.
The %g and %G conversions print the argument in the style of %e or %E (respectively) if the exponent would be less than -4 or greater than or equal to the precision; otherwise they use the %f style. Trailing zeros are removed from the fractional portion of the result and a decimal-point character appears only if it is followed by a digit.
The %a and %A conversions are meant for representing floating-point numbers exactly in textual form so that they can be exchanged as texts between different programs and/or machines. The numbers are represented is the form [-]0xh.hhhp[+|-]dd. At the left of the decimal-point character exactly one digit is print. This character is only 0 if the number is denormalized. Otherwise the value is unspecified; it is implementation dependent how many bits are used. The number of hexadecimal digits on the right side of the decimal-point character is equal to the precision. If the precision is zero it is determined to be large enough to provide an exact representation of the number (or it is large enough to distinguish two adjacent values if the FLT_RADIX is not a power of 2, the section called “Floating Point Parameters”). For the %a conversion lower-case characters are used to represent the hexadecimal number and the prefix and exponent sign are printed as 0x and p respectively. Otherwise upper-case characters are used and 0X and P are used for the representation of prefix and exponent string. The exponent to the base of two is printed as a decimal number using at least one digit but at most as many digits as necessary to represent the value exactly.
If the value to be printed represents infinity or a NaN, the output is [-]inf or nan respectively if the conversion specifier is %a, %e, %f, or %g and it is [-]INF or NAN respectively if the conversion is %A, %E, or %G.
The following flags can be used to modify the behavior:
Left-justify the result in the field. Normally the result is right-justified.
Always include a plus or minus sign in the result.
If the result doesn't start with a plus or minus sign, prefix it with a space instead. Since the + flag ensures that the result includes a sign, this flag is ignored if you supply both of them.
Specifies that the result should always include a decimal point, even if no digits follow it. For the %g and %G conversions, this also forces trailing zeros after the decimal point to be left in place where they would otherwise be removed.
Separate the digits of the integer part of the result into groups as specified by the locale specified for the LC_NUMERIC category; the section called “Generic Numeric Formatting Parameters”. This flag is a GNU extension.
Pad the field with zeros instead of spaces; the zeros are placed after any sign. This flag is ignored if the - flag is also specified.
The precision specifies how many digits follow the decimal-point character for the %f, %e, and %E conversions. For these conversions, the default precision is 6. If the precision is explicitly 0, this suppresses the decimal point character entirely. For the %g and %G conversions, the precision specifies how many significant digits to print. Significant digits are the first digit before the decimal point, and all the digits after it. If the precision is 0 or not specified for %g or %G, it is treated like a value of 1. If the value being printed cannot be expressed accurately in the specified number of digits, the value is rounded to the nearest number that fits.
Without a type modifier, the floating-point conversions use an argument of type double. (By the default argument promotions, any float arguments are automatically converted to double.) The following type modifier is supported:
An uppercase L specifies that the argument is a long double.
Here are some examples showing how numbers print using the various floating-point conversions. All of the numbers were printed using this template string:
"|%13.4a|%13.4f|%13.4e|%13.4g|\n"
Here is the output:
| 0x0.0000p+0| 0.0000| 0.0000e+00| 0| | 0x1.0000p-1| 0.5000| 5.0000e-01| 0.5| | 0x1.0000p+0| 1.0000| 1.0000e+00| 1| | -0x1.0000p+0| -1.0000| -1.0000e+00| -1| | 0x1.9000p+6| 100.0000| 1.0000e+02| 100| | 0x1.f400p+9| 1000.0000| 1.0000e+03| 1000| | 0x1.3880p+13| 10000.0000| 1.0000e+04| 1e+04| | 0x1.81c8p+13| 12345.0000| 1.2345e+04| 1.234e+04| | 0x1.86a0p+16| 100000.0000| 1.0000e+05| 1e+05| | 0x1.e240p+16| 123456.0000| 1.2346e+05| 1.235e+05|
Notice how the %g conversion drops trailing zeros.
This section describes miscellaneous conversions for printf.
The %c conversion prints a single character. In case there is no l modifier the int argument is first converted to an unsigned char. Then, if used in a wide stream function, the character is converted into the corresponding wide character. The - flag can be used to specify left-justification in the field, but no other flags are defined, and no precision or type modifier can be given. For example:
printf ("%c%c%c%c%c", 'h', 'e', 'l', 'l', 'o');
prints hello.
If there is a l modifier present the argument is expected to be of type wint_t. If used in a multibyte function the wide character is converted into a multibyte character before being added to the output. In this case more than one output byte can be produced.
The %s conversion prints a string. If no l modifier is present the corresponding argument must be of type char * (or const char *). If used in a wide stream function the string is first converted in a wide character string. A precision can be specified to indicate the maximum number of characters to write; otherwise characters in the string up to but not including the terminating null character are written to the output stream. The - flag can be used to specify left-justification in the field, but no other flags or type modifiers are defined for this conversion. For example:
printf ("%3s%-6s", "no", "where");
prints nowhere .
If there is a l modifier present the argument is expected to be of type wchar_t (or const wchar_t *).
If you accidentally pass a null pointer as the argument for a %s conversion, the GNU library prints it as (null). We think this is more useful than crashing. But it's not good practice to pass a null argument intentionally.
The %m conversion prints the string corresponding to the error code in errno. the section called “Error Messages”. Thus:
fprintf (stderr, "can't open `%s': %m\n", filename);
is equivalent to:
fprintf (stderr, "can't open `%s': %s\n", filename, strerror (errno));
The %m conversion is a GNU C library extension.
The %p conversion prints a pointer value. The corresponding argument must be of type void *. In practice, you can use any type of pointer.
In the GNU system, non-null pointers are printed as unsigned integers, as if a %#x conversion were used. Null pointers print as (nil). (Pointers might print differently in other systems.)
For example:
printf ("%p", "testing");
prints 0x followed by a hexadecimal number--the address of the string constant "testing". It does not print the word testing.
You can supply the - flag with the %p conversion to specify left-justification, but no other flags, precision, or type modifiers are defined.
The %n conversion is unlike any of the other output conversions. It uses an argument which must be a pointer to an int, but instead of printing anything it stores the number of characters printed so far by this call at that location. The h and l type modifiers are permitted to specify that the argument is of type short int * or long int * instead of int *, but no flags, field width, or precision are permitted.
For example,
int nchar; printf ("%d %s%n\n", 3, "bears", nchar);
prints:
3 bears
and sets nchar to 7, because 3 bears is seven characters.
The %% conversion prints a literal % character. This conversion doesn't use an argument, and no flags, field width, precision, or type modifiers are permitted.
This section describes how to call printf and related functions. Prototypes for these functions are in the header file stdio.h. Because these functions take a variable number of arguments, you must declare prototypes for them before using them. Of course, the easiest way to make sure you have all the right prototypes is to just include stdio.h. int function>printf/function> (const char *template, …) The printf function prints the optional arguments under the control of the template string template to the stream stdout. It returns the number of characters printed, or a negative value if there was an output error.
int function>wprintf/function> (const wchar_t *template, …) The wprintf function prints the optional arguments under the control of the wide template string template to the stream stdout. It returns the number of wide characters printed, or a negative value if there was an output error.
int function>fprintf/function> (FILE *stream, const char *template, …) This function is just like printf, except that the output is written to the stream stream instead of stdout.
int function>fwprintf/function> (FILE *stream, const wchar_t *template, …) This function is just like wprintf, except that the output is written to the stream stream instead of stdout.
int function>sprintf/function> (char *s, const char *template, …) This is like printf, except that the output is stored in the character array s instead of written to a stream. A null character is written to mark the end of the string.
The sprintf function returns the number of characters stored in the array s, not including the terminating null character.
The behavior of this function is undefined if copying takes place between objects that overlap--for example, if s is also given as an argument to be printed under control of the %s conversion. the section called “Copying and Concatenation”.
Warning: The sprintf function can be dangerous because it can potentially output more characters than can fit in the allocation size of the string s. Remember that the field width given in a conversion specification is only a minimum value.
To avoid this problem, you can use snprintf or asprintf, described below.
int function>swprintf/function> (wchar_t *s, size_t size, const wchar_t *template, …) This is like wprintf, except that the output is stored in the wide character array ws instead of written to a stream. A null wide character is written to mark the end of the string. The size argument specifies the maximum number of characters to produce. The trailing null character is counted towards this limit, so you should allocate at least size wide characters for the string ws.
The return value is the number of characters generated for the given input, excluding the trailing null. If not all output fits into the provided buffer a negative value is returned. You should try again with a bigger output string. Note: this is different from how snprintf handles this situation.
Note that the corresponding narrow stream function takes fewer parameters. swprintf in fact corresponds to the snprintf function. Since the sprintf function can be dangerous and should be avoided the ISO C committee refused to make the same mistake again and decided to not define an function exactly corresponding to sprintf.
int function>snprintf/function> (char *s, size_t size, const char *template, …) The snprintf function is similar to sprintf, except that the size argument specifies the maximum number of characters to produce. The trailing null character is counted towards this limit, so you should allocate at least size characters for the string s.
The return value is the number of characters which would be generated for the given input, excluding the trailing null. If this value is greater or equal to size, not all characters from the result have been stored in s. You should try again with a bigger output string. Here is an example of doing this:
/* Construct a message describing the value of a variable whose name is name and whose value is value. */ char * make_message (char *name, char *value) { /* Guess we need no more than 100 chars of space. */ int size = 100; char *buffer = (char *) xmalloc (size); int nchars; if (buffer == NULL) return NULL; /* Try to print in the allocated space. */ nchars = snprintf (buffer, size, "value of %s is %s", name, value); if (nchars = size) { /* Reallocate buffer now that we know how much space is needed. */ buffer = (char *) xrealloc (buffer, nchars + 1); if (buffer != NULL) /* Try again. */ snprintf (buffer, size, "value of %s is %s", name, value); } /* The last call worked, return the string. */ return buffer; }
In practice, it is often easier just to use asprintf, below.
Attention: In versions of the GNU C library prior to 2.1 the return value is the number of characters stored, not including the terminating null; unless there was not enough space in s to store the result in which case -1 is returned. This was changed in order to comply with the ISO C99 standard.
The functions in this section do formatted output and place the results in dynamically allocated memory.
int function>asprintf/function> (char **ptr, const char *template, …) This function is similar to sprintf, except that it dynamically allocates a string (as with malloc; the section called “Unconstrained Allocation”) to hold the output, instead of putting the output in a buffer you allocate in advance. The ptr argument should be the address of a char * object, and asprintf stores a pointer to the newly allocated string at that location.
The return value is the number of characters allocated for the buffer, or less than zero if an error occurred. Usually this means that the buffer could not be allocated.
Here is how to use asprintf to get the same result as the snprintf example, but more easily:
/* Construct a message describing the value of a variable whose name is name and whose value is value. */ char * make_message (char *name, char *value) { char *result; if (asprintf (result, "value of %s is %s", name, value) 0) return NULL; return result; }
int function>obstack_printf/function> (struct obstack *obstack, const char *template, …) This function is similar to asprintf, except that it uses the obstack obstack to allocate the space. the section called “Obstacks”.
The characters are written onto the end of the current object. To get at them, you must finish the object with obstack_finish (the section called “Growing Objects ”).
The functions vprintf and friends are provided so that you can define your own variadic printf-like functions that make use of the same internals as the built-in formatted output functions.
The most natural way to define such functions would be to use a language construct to say, "Call printf and pass this template plus all of my arguments after the first five." But there is no way to do this in C, and it would be hard to provide a way, since at the C language level there is no way to tell how many arguments your function received.
Since that method is impossible, we provide alternative functions, the vprintf series, which lets you pass a va_list to describe "all of my arguments after the first five."
When it is sufficient to define a macro rather than a real function, the GNU C compiler provides a way to do this much more easily with macros. For example:
#define myprintf(a, b, c, d, e, rest...) \ printf (mytemplate , ## rest...)
, for details. But this is limited to macros, and does not apply to real functions at all.
Before calling vprintf or the other functions listed in this section, you must call va_start (the section called “Variadic Functions”) to initialize a pointer to the variable arguments. Then you can call va_arg to fetch the arguments that you want to handle yourself. This advances the pointer past those arguments.
Once your va_list pointer is pointing at the argument of your choice, you are ready to call vprintf. That argument and all subsequent arguments that were passed to your function are used by vprintf along with the template that you specified separately.
In some other systems, the va_list pointer may become invalid after the call to vprintf, so you must not use va_arg after you call vprintf. Instead, you should call va_end to retire the pointer from service. However, you can safely call va_start on another pointer variable and begin fetching the arguments again through that pointer. Calling vprintf does not destroy the argument list of your function, merely the particular pointer that you passed to it.
GNU C does not have such restrictions. You can safely continue to fetch arguments from a va_list pointer after passing it to vprintf, and va_end is a no-op. (Note, however, that subsequent va_arg calls will fetch the same arguments which vprintf previously used.)
Prototypes for these functions are declared in stdio.h. int function>vprintf/function> (const char *template, va_list ap) This function is similar to printf except that, instead of taking a variable number of arguments directly, it takes an argument list pointer ap.
int function>vwprintf/function> (const wchar_t *template, va_list ap) This function is similar to wprintf except that, instead of taking a variable number of arguments directly, it takes an argument list pointer ap.
int function>vfprintf/function> (FILE *stream, const char *template, va_list ap) This is the equivalent of fprintf with the variable argument list specified directly as for vprintf.
int function>vfwprintf/function> (FILE *stream, const wchar_t *template, va_list ap) This is the equivalent of fwprintf with the variable argument list specified directly as for vwprintf.
int function>vsprintf/function> (char *s, const char *template, va_list ap) This is the equivalent of sprintf with the variable argument list specified directly as for vprintf.
int function>vswprintf/function> (wchar_t *s, size_t size, const wchar_t *template, va_list ap) This is the equivalent of swprintf with the variable argument list specified directly as for vwprintf.
int function>vsnprintf/function> (char *s, size_t size, const char *template, va_list ap) This is the equivalent of snprintf with the variable argument list specified directly as for vprintf.
int function>vasprintf/function> (char **ptr, const char *template, va_list ap) The vasprintf function is the equivalent of asprintf with the variable argument list specified directly as for vprintf.
int function>obstack_vprintf/function> (struct obstack *obstack, const char *template, va_list ap) The obstack_vprintf function is the equivalent of obstack_printf with the variable argument list specified directly as for vprintf.
Here's an example showing how you might use vfprintf. This is a function that prints error messages to the stream stderr, along with a prefix indicating the name of the program (the section called “Error Messages”, for a description of program_invocation_short_name).
#include stdio.h #include stdarg.h void eprintf (const char *template, ...) { va_list ap; extern char *program_invocation_short_name; fprintf (stderr, "%s: ", program_invocation_short_name); va_start (ap, template); vfprintf (stderr, template, ap); va_end (ap); }
You could call eprintf like this:
eprintf ("file `%s' does not exist\n", filename);
In GNU C, there is a special construct you can use to let the compiler know that a function uses a printf-style format string. Then it can check the number and types of arguments in each call to the function, and warn you when they do not match the format string. For example, take this declaration of eprintf:
void eprintf (const char *template, ...) __attribute__ ((format (printf, 1, 2)));
This tells the compiler that eprintf uses a format string like printf (as opposed to scanf; the section called “Formatted Input ”); the format string appears as the first argument; and the arguments to satisfy the format begin with the second. , for more information.
You can use the function parse_printf_format to obtain information about the number and types of arguments that are expected by a given template string. This function permits interpreters that provide interfaces to printf to avoid passing along invalid arguments from the user's program, which could cause a crash.
All the symbols described in this section are declared in the header file printf.h.
size_t function>parse_printf_format/function> (const char *template, size_t n, int *argtypes) This function returns information about the number and types of arguments expected by the printf template string template. The information is stored in the array argtypes; each element of this array describes one argument. This information is encoded using the various PA_ macros, listed below.
The argument n specifies the number of elements in the array argtypes. This is the maximum number of elements that parse_printf_format will try to write.
parse_printf_format returns the total number of arguments required by template. If this number is greater than n, then the information returned describes only the first n arguments. If you want information about additional arguments, allocate a bigger array and call parse_printf_format again.
The argument types are encoded as a combination of a basic type and modifier flag bits.
int function>PA_FLAG_MASK/function> This macro is a bitmask for the type modifier flag bits. You can write the expression (argtypes[i] PA_FLAG_MASK) to extract just the flag bits for an argument, or (argtypes[i] ~PA_FLAG_MASK) to extract just the basic type code.
Here are symbolic constants that represent the basic types; they stand for integer values.
This specifies that the base type is int.
This specifies that the base type is int, cast to char.
This specifies that the base type is char *, a null-terminated string.
This specifies that the base type is void *, an arbitrary pointer.
This specifies that the base type is float.
This specifies that the base type is double.
You can define additional base types for your own programs as offsets from PA_LAST. For example, if you have data types foo and bar with their own specialized printf conversions, you could define encodings for these types as:
#define PA_FOO PA_LAST #define PA_BAR (PA_LAST + 1)
Here are the flag bits that modify a basic type. They are combined with the code for the basic type using inclusive-or.
If this bit is set, it indicates that the encoded type is a pointer to the base type, rather than an immediate value. For example, PA_INT|PA_FLAG_PTR represents the type int *.
If this bit is set, it indicates that the base type is modified with short. (This corresponds to the h type modifier.)
If this bit is set, it indicates that the base type is modified with long. (This corresponds to the l type modifier.)
If this bit is set, it indicates that the base type is modified with long long. (This corresponds to the L type modifier.)
This is a synonym for PA_FLAG_LONG_LONG, used by convention with a base type of PA_DOUBLE to indicate a type of long double.
For an example of using these facilities, see the section called “Example of Parsing a Template String”.
Here is an example of decoding argument types for a format string. We assume this is part of an interpreter which contains arguments of type NUMBER, CHAR, STRING and STRUCTURE (and perhaps others which are not valid here).
/* Test whether the nargs specified objects in the vector args are valid for the format string format: if so, return 1. If not, return 0 after printing an error message. */ int validate_args (char *format, int nargs, OBJECT *args) { int *argtypes; int nwanted; /* Get the information about the arguments. Each conversion specification must be at least two characters long, so there cannot be more specifications than half the length of the string. */ argtypes = (int *) alloca (strlen (format) / 2 * sizeof (int)); nwanted = parse_printf_format (string, nelts, argtypes); /* Check the number of arguments. */ if (nwanted nargs) { error ("too few arguments (at least %d required)", nwanted); return 0; } /* Check the C type wanted for each argument and see if the object given is suitable. */ for (i = 0; i nwanted; i++) { int wanted; if (argtypes[i] PA_FLAG_PTR) wanted = STRUCTURE; else switch (argtypes[i] ~PA_FLAG_MASK) { case PA_INT: case PA_FLOAT: case PA_DOUBLE: wanted = NUMBER; break; case PA_CHAR: wanted = CHAR; break; case PA_STRING: wanted = STRING; break; case PA_POINTER: wanted = STRUCTURE; break; } if (TYPE (args[i]) != wanted) { error ("type mismatch for arg number %d", i); return 0; } } return 1; }