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

FreeBSD Manual Pages


home | help
PRINTF(3V)							    PRINTF(3V)

       printf, fprintf,	sprintf	- formatted output conversion

       #include	<stdio.h>

       int printf(format [ , arg... ] )
       char *format;

       int fprintf(stream, format [ , arg... ] )
       FILE *stream;
       char *format;

       char *sprintf(s,	format [ , arg... ] )
       char *s,	*format;

       The routines above are available	as shown, except:

       int sprintf(s, format [ , arg...	] )
       char *s,	*format;

       The following are provided for XPG2 compatibility:

       #define	 nl_printf	printf
       #define	 nl_fprintf	fprintf
       #define	 nl_sprintf	sprintf

       printf()	places output on the standard output stream stdout.  fprintf()
       places output on	the named output stream.  sprintf()  places  "output",
       followed	 by  the null character	(\0), in consecutive bytes starting at
       *s; it is the user's responsibility to ensure that  enough  storage  is

       Each  of	 these	functions converts, formats, and prints	its args under
       control of the format.  The format is a character string	which contains
       two  types of objects: plain characters,	which are simply copied	to the
       output stream, and conversion specifications, each of which causes con-
       version	and  printing of zero or more args.  The results are undefined
       if there	are insufficient args for the format.  If the  format  is  ex-
       hausted while args remain, the excess args are simply ignored.

       Each  conversion	 specification is introduced by	either the % character
       or by the character sequence %digit$, after which the following	appear
       in sequence:

	      o	 Zero  or  more	flags, which modify the	meaning	of the conver-
		 sion specification.

	      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	on the left (or	right, if  the
		 left-adjustment flag `-', described below, has	been given) to
		 the field width.  The padding is with blanks unless the field
		 width digit string starts with	a zero,	in which case the pad-
		 ding is with zeros.

	      o	 A precision that gives	the minimum number of digits to	appear
		 for the d, i, o, u, x,	or X conversions, the number of	digits
		 to appear after the decimal point for the e, E, and f conver-
		 sions,	the maximum number of significant digits for the g and
		 G conversion, or the  maximum	number	of  characters	to  be
		 printed  from	a string in s conversion.  The precision takes
		 the form of a period (.)  followed by a decimal digit string;
		 a  null  digit	 string	is treated as zero.  Padding specified
		 by the	precision overrides the	padding	specified by the field

	      o	 An  optional  l (ell) specifying that a following d, i, o, u,
		 x, or X conversion character applies to a long	 integer  arg.
		 An l before any other conversion character is ignored.

	      o	 A  character  that indicates the type of conversion to	be ap-

       A field width or	precision or both may be indicated by an asterisk  (*)
       instead	of  a digit string.  In	this case, an integer arg supplies the
       field width or precision.  The arg that is actually  converted  is  not
       fetched	until  the  conversion	letter is seen,	so the args specifying
       field width or precision	must appear before the arg (if any) to be con-
       verted.	 A  negative  field width argument is taken as a `-' flag fol-
       lowed by	a positive field width.	 If the	precision  argument  is	 nega-
       tive, it	will be	changed	to zero.

       The flag	characters and their meanings are:
       -	 The  result  of  the conversion will be left-justified	within
		 the field.
       +	 The result of a signed	conversion will	always	begin  with  a
		 sign (+ or -).
       blank	 If  the first character of a signed conversion	is not a sign,
		 a blank will be prefixed to the result.  This implies that if
		 the blank and + flags both appear, the	blank flag will	be ig-
       #	 This flag specifies that the value is to be converted	to  an
		 "alternate  form".   For  c,  d, i, s,	and u conversions, the
		 flag has no effect.  For o conversion,	it increases the  pre-
		 cision	 to  force the first digit of the result to be a zero.
		 For x or X conversion,	a non-zero result will have 0x	or  0X
		 prefixed  to  it.  For	e, E, f, g, and	G conversions, the re-
		 sult will always contain a decimal point, even	if  no	digits
		 follow	 the  point  (normally,	a decimal point	appears	in the
		 result	of these conversions only if a digit follows it).  For
		 g and G conversions, trailing zeroes will not be removed from
		 the result (which they	normally are).

       The conversion characters and their meanings are:

		 The integer arg is converted to signed	decimal	(d or i),  un-
		 signed	octal (o), unsigned decimal (u), or unsigned hexadeci-
		 mal notation (x, p, and X), respectively; the letters	abcdef
		 are  used for x and p conversion and the letters ABCDEF for X
		 conversion.  The precision specifies the  minimum  number  of
		 digits	 to appear; if the value being converted can be	repre-
		 sented	in fewer digits, it will be expanded with leading  ze-
		 roes.	 For  compatibility  with older	versions, padding with
		 leading zeroes	may alternatively be specified by prepending a
		 zero  to the field width.  This does not imply	an octal value
		 for the field width.  The default precision is	1.  The	result
		 of converting a zero value with a precision of	zero is	a null
       f	 The float or double arg is converted to decimal  notation  in
		 the style ``[-]ddd.ddd'' where	the number of digits after the
		 decimal point is equal	to the	precision  specification.   If
		 the  precision	 is missing, 6 digits are given; if the	preci-
		 sion is explicitly 0, no digits  and  no  decimal  point  are
       e,E	 The   float   or   double  arg	 is  converted	in  the	 style
		 "[-]d.ddde+-ddd," where there is one digit before the decimal
		 point	and the	number of digits after it is equal to the pre-
		 cision; when the precision is missing,	6 digits are produced;
		 if  the  precision  is	zero, no decimal point appears.	 The E
		 format	code will produce a number with	E instead of e	intro-
		 ducing	 the  exponent.	 The exponent always contains at least
		 two digits.
       g,G	 The float or double arg is printed in style f	or  e  (or  in
		 style	E  in the case of a G format code), with the precision
		 specifying the	number of significant digits.  The style  used
		 depends  on  the  value  converted: style e or	E will be used
		 only if the exponent resulting	from the  conversion  is  less
		 than  -4  or greater than the precision.  Trailing zeroes are
		 removed from the result; a decimal point appears only	if  it
		 is followed by	a digit.

       The e, E, f, g, and G formats print IEEE	indeterminate values (infinity
       or not-a-number)	as "Infinity" or "NaN" respectively.

       c	 The character arg is printed.
       s	 The arg is taken to be	a string (character pointer) and char-
		 acters	 from  the  string  are	printed	until a	null character
		 (\0) is encountered or	until the number of  characters	 indi-
		 cated by the precision	specification is reached.  If the pre-
		 cision	is missing, it is taken	to be infinite,	so all charac-
		 ters  up  to  the  first  null	character are printed.	A NULL
		 value for arg will yield undefined results.
       n	 The argument arg is a pointer to an  integer  into  which  is
		 written the number of characters written to the output	so far
		 by this call to one of	the printf() functions.	  No  argument
		 is converted.
       %	 Print a %; no argument	is converted.

       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 simply expanded to contain the conversion result.  Padding
       takes place only	if the specified field width exceeds the actual	width.
       Characters  generated  by  printf()  and	 fprintf()  are	 printed as if
       putc(3S)	had been called.

       All forms of the	printf() functions allow for the insertion of  a  lan-
       guage  dependent	radix character	in the output string.  The radix char-
       acter is	defined	by the program's locale	(category LC_NUMERIC).	In the
       "C"  locale,  or	 in a locale where the radix character is not defined,
       the radix character defaults to `.'.

       Conversions can be applied to the nth argument in  the  argument	 list,
       rather  than  the  next	unused argument.  In this case,	the conversion
       character % is replaced by the sequence %digit$,	where digit is a deci-
       mal  integer  n in the range [1,9], giving the position of the argument
       in the argument list.  This feature provides for	the definition of for-
       mat  strings  that select arguments in an order appropriate to specific

       In format strings containing the	%digit$	form of	a conversion  specifi-
       cation,	a  field  width	 or precision may be indicated by the sequence
       *digit$,	where digit is a decimal integer in the	range [1,9] giving the
       position	 in  the  argument list	of an integer arg containing the field
       width or	precision.

       The format string can contain either numbered  argument	specifications
       (that  is,  %digit$ and *digit$), or unnumbered argument	specifications
       (that is	% and *), but not both.	The results of mixing numbered and un-
       numbered	 specifications	is undefined.  When numbered argument specifi-
       cations are used, specifying the	nth argument  requires	that  all  the
       leading	arguments,  from  the first to the (n-1)th be specified	in the
       format string.

       XPG2 requires that nl_printf, nl_fprintf	and nl_sprintf be  defined  as
       printf, fprintf and sprintf, respectively for backward compatibility

       On  success,  printf()  and  fprintf()  return the number of characters
       transmitted, excluding the null character.   On	failure,  they	return

       sprintf() returns s.

       On success, sprintf() returns the number	of characters transmitted, ex-
       cluding the null	character.  On failure,	it returns EOF.

	      printf(format, weekday, month, day, hour,	min);

       In American usage, format could be a pointer to the string:

	      "%s, %s %d, %d:%.2d\n"

       producing the message:

	      Sunday, July 3,10:02

       Whereas for German usage, format	could be a pointer to the string:

	      "%1$s, %3$d.%2$s,%4$d:%5$.2d\n"

       producing the message:

	      Sonntag, 3.Juli,10:02

       To print	pi to 5	decimal	places:

	      printf("pi = %.5f", 4 * atan(1. 0));

       econvert(3),   putc(3S),	   scanf(3V),	 setlocale(3V),	   varargs(3),

       Very wide fields	(>128 characters) fail.

				21 January 1990			    PRINTF(3V)


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

home | help