The functions in the printf() family produce output according to a for mat as described below.
The functions printf() and vprintf() write output to stdout, the standard output stream; fprintf() and vfprintf() write output to the given output stream; sprintf(), snprintf(), vsprintf() and vsnprintf() write to the character string str.
The functions snprintf() and vsnprintf() write at most size bytes (including the trailing null byte (‘\0’)) to str.
The functions vprintf(), vfprintf(), vsprintf(), vsnprintf() are equiv alent to the functions printf(), fprintf(), sprintf(), snprintf(), respectively, except that they are called with a va_list instead of a variable number of arguments. These functions do not call the va_end macro. Because they invoke the va_arg macro, the value of ap is undefined after the call. See stdarg(3).
These eight functions write the output under the control of a format string that specifies how subsequent arguments (or arguments accessed via the variable-length argument facilities of stdarg(3)) are converted.
C99 and POSIX.1-2001 specify that the results are undefined if a call to sprintf(), snprintf(), vsprintf(), or vsnprintf() would cause copying to take place between objects that overlap (e.g., if the target string array and one of the supplied input arguments refer to the same buffer).
Return value Upon successful return, these functions return the number of characters printed (not including the trailing ‘\0’ used to end output to strings).
The functions snprintf() and vsnprintf() do not write more than size bytes (including the trailing ‘\0’). If the output was truncated due to this limit then the return value is the number of characters (not including the trailing ‘\0’) which would have been written to the final string if enough space had been available. Thus, a return value of size or more means that the output was truncated. (See also below under NOTES.)
If an output error is encountered, a negative value is returned.
Format of the format string
The format string is a character string, beginning and ending in its initial shift state, if any. The format string is composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the character %, and ends with a conversion specifier. In between there may be (in this order) zero or more flags, an optional minimum field width, an optional precision and an optional length modifier.
The arguments must correspond properly (after type promotion) with the conversion specifier. By default, the arguments are used in the order given, where each ‘*’ and each conversion specifier asks for the next argument (and it is an error if insufficiently many arguments are given). One can also specify explicitly which argument is taken, at each place where an argument is required, by writing “%m$” instead of ‘%’ and “*m$” instead of ‘*’, where the decimal integer m denotes the position in the argument list of the desired argument, indexed starting
printf(“%*d”, width, num);
printf(“%2$*1$d”, width, num);
are equivalent. The second style allows repeated references to the same argument. The C99 standard does not include the style using ‘$’, which comes from the Single Unix Specification. If the style using ‘$’ is used, it must be used throughout for all conversions taking an argument and all width and precision arguments, but it may be mixed with “%%” formats which do not consume an argument.
There may be no gaps in the numbers of arguments specified using ‘$’; for example, if arguments 1 and 3 are specified, argument 2 must also be specified somewhere in the format string.