- a developer's blog

printf() Manual

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
from 1.


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.