Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PRINTF(3)		 BSD Library Functions Manual		     PRINTF(3)

     printf, fprintf, sprintf, snprintf, asprintf, vprintf, vfprintf,
     vsprintf, vsnprintf, vasprintf -- formatted output	conversion

     Standard C	Library	(libc, -lc)

     #include <stdio.h>

     printf(const char *format,	...);

     fprintf(FILE *stream, const char *format, ...);

     sprintf(char *str,	const char *format, ...);

     snprintf(char *str, size_t	size, const char *format, ...);

     asprintf(char **ret, const	char *format, ...);

     #include <stdarg.h>

     vprintf(const char	*format, va_list ap);

     vfprintf(FILE *stream, const char *format,	va_list	ap);

     vsprintf(char *str, const char *format, va_list ap);

     vsnprintf(char *str, size_t size, const char *format, va_list ap);

     vasprintf(char **ret, const char *format, va_list ap);

     The printf() family of functions produces output according	to a format as
     described below.  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;	and asprintf() and vasprintf() dynami-
     cally allocate a new string with malloc(3).

     These 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 for out-

     These functions return the	number of characters printed (not including
     the trailing `\0' used to end output to strings) or a negative value if
     an	output error occurs, except for	snprintf() and vsnprintf(), which re-
     turn the number of	characters that	would have been	printed	if the size
     were unlimited (again, not	including the final `\0').

     Asprintf()	and vasprintf()	set *ret to be a pointer to a buffer suffi-
     ciently large to hold the formatted string.  This pointer should be
     passed to free(3) to release the allocated	storage	when it	is no longer
     needed.  If sufficient space cannot be allocated, asprintf() and
     vasprintf() will return -1	and set	ret to be a NULL pointer.

     Snprintf()	and vsnprintf()	will write at most size-1 of the characters
     printed into the output string (the size'th character then	gets the ter-
     minating `\0'); if	the return value is greater than or equal to the size
     argument, the string was too short	and some of the	printed	characters
     were discarded.

     Sprintf() and vsprintf() effectively assume an infinite size.

     The format	string is composed of zero or more directives: ordinary	char-
     acters (not %), which are copied unchanged	to the output stream; and con-
     version specifications, each of which results in fetching zero or more
     subsequent	arguments.  Each conversion specification is introduced	by the
     % character.  The arguments must correspond properly (after type promo-
     tion) with	the conversion specifier.  After the %,	the following appear
     in	sequence:

     +o	 An optional field, consisting of a decimal digit string followed by a
	 $, specifying the next	argument to access.  If	this field is not pro-
	 vided,	the argument following the last	argument accessed will be
	 used.	Arguments are numbered starting	at 1.  If unaccessed arguments
	 in the	format string are interspersed with ones that are accessed the
	 results will be indeterminate.

     +o	 Zero or more of the following flags:

	 -   A # character specifying that the value should be converted to an
	     "alternate	form".	For c, d, i, n,	p, s, and u conversions, this
	     option has	no effect.  For	o conversions, the precision of	the
	     number is increased to force the first character of the output
	     string to a zero (except if a zero	value is printed with an ex-
	     plicit precision of zero).	 For x and X conversions, a non-zero
	     result has	the string `0x'	(or `0X' for X conversions) prepended
	     to	it.  For e, E, f, g, and G conversions,	the result will	always
	     contain a decimal point, even if no digits	follow it (normally, a
	     decimal point appears in the results of those conversions only if
	     a digit follows).	For g and G conversions, trailing zeros	are
	     not removed from the result as they would otherwise be.

	 -   A 0 (zero)	character specifying zero padding.  For	all conver-
	     sions except n, the converted value is padded on the left with
	     zeros rather than blanks.	If a precision is given	with a numeric
	     conversion	(d, i, o, u, i,	x, and X), the 0 flag is ignored.

	 -   A negative	field width flag - indicates the converted value is to
	     be	left adjusted on the field boundary.  Except for n conver-
	     sions, the	converted value	is padded on the right with blanks,
	     rather than on the	left with blanks or zeros.  A -	overrides a 0
	     if	both are given.

	 -   A space, specifying that a	blank should be	left before a positive
	     number produced by	a signed conversion (d,	e, E, f, g, G, or i).

	 -   A + character specifying that a sign always be placed before a
	     number produced by	a signed conversion.  A	+ overrides a space if
	     both are used.

     +o	 An optional decimal digit string specifying a minimum field width.
	 If the	converted value	has fewer characters than the field width, it
	 will be padded	with spaces on the left	(or right, if the left-adjust-
	 ment flag has been given) to fill out the field width.

     +o	 An optional precision,	in the form of a period	. followed by an op-
	 tional	digit string.  If the digit string is omitted, the precision
	 is taken as zero.  This gives the minimum number of digits to appear
	 for d,	i, o, u, x, and	X conversions, the number of digits to appear
	 after the decimal-point for e,	E, and f conversions, the maximum num-
	 ber of	significant digits for g and G conversions, or the maximum
	 number	of characters to be printed from a string for s	conversions.

     +o	 The optional character	h, specifying that a following d, i, o,	u, x,
	 or X conversion corresponds to	a short	int or unsigned	short int ar-
	 gument, or that a following n conversion corresponds to a pointer to
	 a short int argument.

     +o	 The optional character	l (ell)	specifying that	a following d, i, o,
	 u, x, or X conversion applies to a pointer to a long int or unsigned
	 long int argument, or that a following	n conversion corresponds to a
	 pointer to a long int argument.

     +o	 The optional characters ll (ell ell) specifying that a	following d,
	 i, o, u, x, or	X conversion applies to	a pointer to a long long int
	 or unsigned long long int argument, or	that a following n conversion
	 corresponds to	a pointer to a long long int argument.

     +o	 The optional character	q, specifying that a following d, i, o,	u, x,
	 or X conversion corresponds to	a quad int or unsigned quad int	argu-
	 ment, or that a following n conversion	corresponds to a pointer to a
	 quad int argument.

     +o	 The character L specifying that a following e,	E, f, g, or G conver-
	 sion corresponds to a long double argument.

     +o	 A character that specifies the	type of	conversion to be applied.

     A field width or precision, or both, may be indicated by an asterisk `*'
     or	an asterisk followed by	one or more decimal digits and a `$' instead
     of	a digit	string.	 In this case, an int argument supplies	the field
     width or precision.  A negative field width is treated as a left adjust-
     ment flag followed	by a positive field width; a negative precision	is
     treated as	though it were missing.	 If a single format directive mixes
     positional	(nn$) and non-positional arguments, the	results	are undefined.

     The conversion specifiers and their meanings are:

     diouxX  The int (or appropriate variant) argument is converted to signed
	     decimal (d	and i),	unsigned octal (o), unsigned decimal (u), or
	     unsigned hexadecimal (x and X) notation.  The letters abcdef are
	     used for x	conversions; the letters ABCDEF	are used for X conver-
	     sions.  The precision, if any, gives the minimum number of	digits
	     that must appear; if the converted	value requires fewer digits,
	     it	is padded on the left with zeros.

     DOU     The long int argument is converted	to signed decimal, unsigned
	     octal, or unsigned	decimal, as if the format had been ld, lo, or
	     lu	respectively.  These conversion	characters are deprecated, and
	     will eventually disappear.

     eE	     The double	argument is rounded and	converted in the style
	     [-]d.ddde+-dd where there is one digit before the decimal-point
	     character and the number of digits	after it is equal to the pre-
	     cision; if	the precision is missing, it is	taken as 6; if the
	     precision is zero,	no decimal-point character appears.  An	E con-
	     version uses the letter E (rather than e) to introduce the	expo-
	     nent.  The	exponent always	contains at least two digits; if the
	     value is zero, the	exponent is 00.

     f	     The double	argument is rounded and	converted to decimal notation
	     in	the style [-]ddd.ddd, where the	number of digits after the
	     decimal-point character is	equal to the precision specification.
	     If	the precision is missing, it is	taken as 6; if the precision
	     is	explicitly zero, no decimal-point character appears.  If a
	     decimal point appears, at least one digit appears before it.

     gG	     The double	argument is converted in style f or e (or E for	G con-
	     versions).	 The precision specifies the number of significant
	     digits.  If the precision is missing, 6 digits are	given; if the
	     precision is zero,	it is treated as 1.  Style e is	used if	the
	     exponent from its conversion is less than -4 or greater than or
	     equal to the precision.  Trailing zeros are removed from the
	     fractional	part of	the result; a decimal point appears only if it
	     is	followed by at least one digit.

     c	     The int argument is converted to an unsigned char,	and the	re-
	     sulting character is written.

     s	     The char *	argument is expected to	be a pointer to	an array of
	     character type (pointer to	a string).  Characters from the	array
	     are written up to (but not	including) a terminating NUL charac-
	     ter; if a precision is specified, no more than the	number speci-
	     fied are written.	If a precision is given, no null character
	     need be present; if the precision is not specified, or is greater
	     than the size of the array, the array must	contain	a terminating
	     NUL character.

     p	     The void *	pointer	argument is printed in hexadecimal (as if by
	     `%#x' or `%#lx').

     n	     The number	of characters written so far is	stored into the	inte-
	     ger indicated by the int *	(or variant) pointer argument.	No ar-
	     gument is converted.

     %	     A `%' is written.	No argument is converted.  The complete	con-
	     version specification is `%%'.

     In	no case	does a non-existent or small field width cause truncation of a
     field; if the result of a conversion is wider than	the field width, the
     field is expanded to contain the conversion result.

     To	print a	date and time in the form "Sunday, July	3, 10:02", where
     weekday and month are pointers to strings:

	   #include <stdio.h>
	   fprintf(stdout, "%s,	%s %d, %.2d:%.2d\n",
		   weekday, month, day,	hour, min);

     To	print pi to five decimal places:

	   #include <math.h>
	   #include <stdio.h>
	   fprintf(stdout, "pi = %.5f\n", 4 * atan(1.0));

     To	allocate a 128 byte string and print into it:

	   #include <stdio.h>
	   #include <stdlib.h>
	   #include <stdarg.h>
	   char	*newfmt(const char *fmt, ...)
			   char	*p;
			   va_list ap;
			   if ((p = malloc(128)) == NULL)
				   return (NULL);
			   va_start(ap,	fmt);
			   (void) vsnprintf(p, 128, fmt, ap);
			   return (p);

     In	addition to the	errors documented for the write(2) system call,	the
     printf() family of	functions may fail if:

     [ENOMEM]		Insufficient storage space is available.

     printf(1),	scanf(3)

     The fprintf(), printf(), sprintf(), vprintf(), vfprintf(),	and vsprintf()
     functions conform to ISO/IEC 9899:1990 ("ISO C90").

     The functions asprintf() and vasprintf() first appeared in	the GNU	C li-
     brary.  These were	implemented by Peter Wemm <> in
     FreeBSD 2.2, but were later replaced with a different implementation from
     Todd C. Miller <>	for OpenBSD 2.3.

     The conversion formats %D,	%O, and	are not	standard and are provided only
     for backward compatibility.  The effect of	padding	the format with	zeros
     (either by	the 0 flag or by specifying a precision), and the benign ef-
     fect (i.e., none) of the #	flag on	%n and %p conversions, as well as
     other nonsensical combinations such as %Ld, are not standard; such	combi-
     nations should be avoided.

     Because sprintf() and vsprintf() assume an	infinitely long	string,	call-
     ers must be careful not to	overflow the actual space; this	is often hard
     to	assure.	 For safety, programmers should	use the	snprintf() interface
     instead.  Unfortunately, this interface is	not portable.

BSD				 March 2, 2003				   BSD


Want to link to this manual page? Use this URL:

home | help