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

FreeBSD Manual Pages

  
 
  

home | help
printf(3C)		 Standard C Library Functions		    printf(3C)

NAME
       printf, fprintf,	sprintf, snprintf - print formatted output

SYNOPSIS
       #include	<stdio.h>

       int printf(const	char *format, /* args*/	...);

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

       int sprintf(char	*s, const char *format,	/* args*/ ...);

       int snprintf(char *s, size_t n, const char *format, /* args*/ ...);

DESCRIPTION
       The  printf() function places output on the standard output stream std-
       out.

       The fprintf() function places output on	on  the	 named	output	stream
       stream.

       The  sprintf()  function	places output, followed	by the null byte (\0),
       in consecutive bytes starting at	s; it is the user's responsibility  to
       ensure that enough storage is available.

       The  snprintf() function	is identical to	sprintf() with the addition of
       the argument n, which specifies the size	of the buffer referred	to  by
       s. The buffer is	always terminated with the null	byte.

       Each of these functions converts, formats, and prints its arguments un-
       der control of the format. The format is	a character string,  beginning
       and  ending in its initial shift	state, if any.	The format is composed
       of zero or more	directives:  ordinary  characters,  which  are	simply
       copied  to  the	output	stream	and conversion specifications, each of
       which results in	the fetching of	zero or	more  arguments.  The  results
       are  undefined  if  there are insufficient arguments for	the format. If
       the format is exhausted while arguments remain,	the  excess  arguments
       are evaluated but are otherwise ignored.

       Conversions  can	be applied to the nth argument after the format	in the
       argument	list, rather than to the next unused argument. In  this	 case,
       the conversion character	% (see below) is replaced by the sequence %n$,
       where n is a decimal integer in the range [1,  NL_ARGMAX],  giving  the
       position	 of  the  argument in the argument list. This feature provides
       for the definition of format strings that select	arguments in an	 order
       appropriate to specific languages (see the EXAMPLES section).

       In format strings containing the	%n$ form of conversion specifications,
       numbered	arguments in the argument list can be referenced from the for-
       mat string as many times	as required.

       In  format  strings containing the % form of conversion specifications,
       each argument in	the argument list is used exactly once.

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

   Conversion Specifications
       Each conversion specification is	introduced by the %  character	or  by
       the  character  sequence	 %n$,  after which the following appear	in se-
       quence:

	  o  An	optional field,	consisting of a	decimal	digit string  followed
	     by	 a  $,	specifying  the	next argument to be converted. If this
	     field is not provided, the	args following the last	argument  con-
	     verted will be used.

	  o  Zero  or  more  flags (in any order), which modify	the meaning of
	     the conversion specification.

	  o  An	optional minimum field width. If the converted value has fewer
	     bytes  than the field width, it will be padded with spaces	by de-
	     fault on the left;	it will	be padded on the right,	if  the	 left-
	     adjustment	 flag  (-),  described	below,	is  given to the field
	     width. The	field width takes the form of  an  asterisk  (*),  de-
	     scribed below, or a decimal integer.

	     If	 the conversion	character is s,	a standard-conforming applica-
	     tion (see standards(5)) interprets	the field width	as the minimum
	     number  of	 bytes to be printed; an application that is not stan-
	     dard-conforming interprets	the field width	as the minimum	number
	     of	 columns  of  screen  display.	For an application that	is not
	     standard-conforming, %10s means if	 the  converted	 value	has  a
	     screen width of 7 columns,	3 spaces would be padded on the	right.

       If  the	format	is %ws,	then the field width should be	interpreted as
       the minimum number of columns of	screen display.

	  o  An	optional precision that	gives the minimum number of digits  to
	     appear  for  the  d,  i, o, u, x, and X conversions (the field is
	     padded with leading zeros); the number of digits to appear	 after
	     the  radix	character for the e, E,	and f conversions, the maximum
	     number of significant digits for the g and	G conversions; or  the
	     maximum  number  of  bytes	to be printed from a string in s and S
	     conversions.  The precision takes the form	of a period  (.)  fol-
	     lowed  either by an asterisk (*), described below,	or an optional
	     decimal digit string, where a null	digit string is	treated	as  0.
	     If	 a  precision appears with any other conversion	character, the
	     behavior is undefined.

	     If	the conversion character is s or S, a standard-conforming  ap-
	     plication (see standards(5)) interprets the precision as the max-
	     imum number of bytes to be	written; an application	 that  is  not
	     standard-conforming  interprets the precision as the maximum num-
	     ber of columns of screen display.	For an application that	is not
	     standard-conforming,  %.5s	 would	print  only the	portion	of the
	     string that would display in 5  screen  columns.	Only  complete
	     characters	are written.

       For  %ws,  the precision	should be interpreted as the maximum number of
       columns of screen display. 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	speci-
       fied by the field width.

	  o  An	optional h specifies that a following d, i, o, u, x, or	X con-
	     version character applies to a type short int  or	type  unsigned
	     short  int	 argument  (the	argument will be promoted according to
	     the integral promotions, and its value converted  to  type	 short
	     int  or unsigned short int	before printing); an optional h	speci-
	     fying that	a  following  n	 conversion  character	applies	 to  a
	     pointer to	a type short int argument; an optional	l (ell)	speci-
	     fying that	a following  d,	i, o, u, x, or	X conversion character
	     applies  to  a  type long int  or	unsigned long int argument; an
	     optional  l (ell) specifying that a following  n conversion char-
	     acter  applies  to	 a pointer to a	type long int argument;	an op-
	     tional  ll	(ell ell)  specifying that a following	d, i, o, u, x,
	     or	  X  conversion	 character applies to a	type long long or  un-
	     signed long long argument;	an optional  ll	(ell ell)   specifying
	     that a following n	conversion character applies to	a pointer to a
	     long long argument; or an optional	L specifying that a  following
	     e,	E, f, g, or G conversion character applies to a	type long dou-
	     ble argument. If an h, l, ll, or L	appears	with any other conver-
	     sion character, the behavior is undefined.

	  o  An	 optional  l  (ell)  specifying	 that a	following c conversion
	     character applies to a wint_t argument; an	optional l (ell) spec-
	     ifying  that  a  following	 s  conversion	character applies to a
	     pointer to	a  wchar_t argument.

	  o  A conversion character (see below)	that  indicates	 the  type  of
	     conversion	to be applied.

       A  field	 width,	 or precision, or both may be indicated	by an asterisk
       (*) . In	this case, an argument of type int supplies the	field width or
       precision. Arguments specifying field width, or precision, or both must
       appear in that order before the argument, if any, to  be	 converted.  A
       negative	 field width is	taken as a - flag followed by a	positive field
       width. A	negative precision is taken as if the precision	were  omitted.
       In  format  strings  containing the %n$ form of a conversion specifica-
       tion, a field width or precision	may be indicated by the	sequence  *m$,
       where m is a decimal integer in the range [1, NL_ARGMAX]	giving the po-
       sition in the argument list (after the format argument) of  an  integer
       argument	containing the field width or precision, for example:

       printf("%1$d:%2$.*3$d:%4$.*3$d\n", hour,	min, precision,	sec);

       The  format  can	 contain either	numbered argument specifications (that
       is, %n$ and *m$), or unnumbered argument	specifications (that is, % and
       *), but normally	not both. The only exception to	this is	that %%	can be
       mixed with the %n$ form.	The results of mixing numbered and  unnumbered
       argument	specifications in a format string are undefined. When numbered
       argument	specifications are used, specifying the	Nth argument  requires
       that  all  the  leading	arguments,  from the first to the (N-1)th, are
       specified in the	format string.

   Flag	Characters
       The flag	characters and their meanings are:

       '     The integer portion of the	result of a  decimal  conversion  (%i,
	     %d, %u, %f, %g, or	%G) will be formatted with thousands' grouping
	     characters. For other conversions the behavior is undefined.  The
	     non-monetary grouping character is	used.

       -     The  result  of  the conversion will be left-justified within the
	     field. The	conversion will	be right-justified if this flag	is not
	     specified.

       +     The  result  of a signed conversion will always begin with	a sign
	     (+	or -). The conversion will begin with a	sign only when a nega-
	     tive value	is converted if	this flag is not specified.

       space If	the first character of a signed	conversion is not a sign or if
	     a signed conversion results in no characters,  a  space  will  be
	     placed  before  the  result.  This	 means that if the space and +
	     flags both	appear,	the space flag will be ignored.

       #     The value is to be	converted to an	alternate form.	For c,	d,  i,
	     s,	 and  u	 conversions, the flag has no effect. For an o conver-
	     sion, it increases	the precision  (if  necessary)	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) prepended to it. For	e,  E,
	     f,	 g,  and G conversions,	the result will	always contain a radix
	     character,	even if	no digits follow the radix character.  Without
	     this  flag,  the  radix  character	appears	in the result of these
	     conversions only if a digit follows it. For g and G  conversions,
	     trailing  zeros  will not be removed from the result as they nor-
	     mally are.

       0     For d, i, o, u, x,	X, e, E, f, g, and G conversions, leading  ze-
	     ros (following any	indication of sign or base) are	used to	pad to
	     the field width; no space padding is performed. If	the  0	and  -
	     flags both	appear,	the 0 flag will	be ignored. For	d, i, o, u, x,
	     and X conversions,	if a precision is specified, the 0  flag  will
	     be	 ignored. If the 0 and ' flags both appear, the	grouping char-
	     acters are	inserted before	zero padding. For  other  conversions,
	     the behavior is undefined.

   Conversion Characters
       Each  conversion	 character results in fetching zero or more arguments.
       The results are undefined if there are insufficient arguments  for  the
       format.	If  the	format is exhausted while arguments remain, the	excess
       arguments are ignored.

       The conversion characters and their meanings are:

       d,i   The int argument is converted to a	signed decimal	in  the	 style
	     [-]dddd.  The precision specifies the minimum number of digits to
	     appear; if	the value being	converted can be represented in	 fewer
	     digits,  it will be expanded with leading zeros. The default pre-
	     cision is 1. The result of	converting 0 with an  explicit	preci-
	     sion of 0 is no characters.

       o     The  unsigned  int	argument is converted to unsigned octal	format
	     in	the style dddd.	The precision specifies	the minimum number  of
	     digits to appear; if the value being converted can	be represented
	     in	fewer digits, it will be expanded with leading zeros. The  de-
	     fault precision is	1. The result of converting 0 with an explicit
	     precision of 0 is no characters.

       u     The unsigned int argument is converted to unsigned	decimal	format
	     in	 the style dddd. The precision specifies the minimum number of
	     digits to appear; if the value being converted can	be represented
	     in	 fewer digits, it will be expanded with	leading	zeros. The de-
	     fault precision is	1. The result of converting 0 with an explicit
	     precision of 0 is no characters.

       x     The  unsigned  int	 argument is converted to unsigned hexadecimal
	     format in the style dddd; the letters abcdef are used. The	preci-
	     sion  specifies  the  minimum  number of digits to	appear;	if the
	     value being converted can be represented in fewer digits, it will
	     be	 expanded  with	leading	zeros. The default precision is	1. The
	     result of converting 0 with an explicit  precision	 of  0	is  no
	     characters.

       X     Behaves  the  same	as the x conversion character except that let-
	     ters ABCDEF are used instead of abcdef.

       f     The double	argument is converted to decimal notation in the style
	     [-]ddd.ddd,  where	the number of digits after the radix character
	     (see setlocale(3C)) is equal to the precision  specification.  If
	     the  precision  is	missing	it is taken as 6; if the  precision is
	     explicitly	0 and the # flag is not	specified, no radix  character
	     appears.  If  a radix character appears, at least 1 digit appears
	     before it.	The value is rounded to	the appropriate	number of dig-
	     its.

       e,E   The  double  argument  is	converted  to the style	[-]d.ddde+-dd,
	     where there is one	digit before the  radix	 character  (which  is
	     non-zero  if  the	argument is non-zero) and the number of	digits
	     after it is equal to the precision. When the precision is missing
	     it	 is  taken  as	6; if the precision is 0 and the # flag	is not
	     specified,	no radix character appears. The	E conversion character
	     will  produce  a number with E instead of e introducing the expo-
	     nent. The exponent	always contains	at least two digits. The value
	     is	rounded	to the appropriate number of digits.

       g,G   The  double argument is printed in	style f	or e (or in style E in
	     the case of a G conversion	character), with the precision	speci-
	     fying  the	number of significant digits. If an explicit precision
	     is	0, it is taken as 1. The style used depends on the value  con-
	     verted:  style e (or E) will be used only if the exponent result-
	     ing from the 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 radix character appears only	if it is  fol-
	     lowed by a	digit.

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

	     If	an l (ell) qualifier is	present, the wint_t argument  is  con-
	     verted  as	if by an ls conversion specification with no precision
	     and an argument that  points  to  a  two-element  array  of  type
	     wchar_t,  the first element of which contains the wint_t argument
	     to	the ls conversion specification	and the	 second	 element  con-
	     tains a null wide-character.

       C     Same as lc.

       wc    The  int argument is converted to a wide character	(wchar_t), and
	     the resulting wide	character is printed.

       s     The argument must be a pointer to an array	of  char.  Bytes  from
	     the   array are written up	to (but	not including) any terminating
	     null byte.	If a precision is specified, a standard-conforming ap-
	     plication	(see standards(5)) will	write only the number of bytes
	     specified by precision; an	application that is not	 standard-con-
	     forming will write	only the portion of the	string that will  dis-
	     play in the number	of columns of screen display specified by pre-
	     cision.  If the precision is not specified, it is taken to	be in-
	     finite, so	all bytes up to	the first null byte  are  printed.  An
	     argument with a null value	will yield undefined results.

	     If	 an  l	(ell)  qualifier  is  present,	the argument must be a
	     pointer to	an array of type wchar_t. Wide-characters from the ar-
	     ray are converted to characters (each as if by a call to the wcr-
	     tomb(3C) function,	with the conversion state described by an  mb-
	     state_t  object initialized to zero before	the first wide-charac-
	     ter is converted) up to and including a  terminating  null	 wide-
	     character.	  The  resulting characters are	written	up to (but not
	     including)	the terminating	null character (byte).	If  no	preci-
	     sion  is specified, the array must	contain	a null wide-character.
	     If	a precision is specified, no more than	that  many  characters
	     (bytes)  are written (including shift sequences, if any), and the
	     array must	contain	a null wide-character if, to equal the charac-
	     ter  sequence  length  given by the precision, the	function would
	     need to access a wide-character one past the end  of  the	array.
	     In	no case	is a partial character written.

       S     Same as ls.

       ws    The argument must be a pointer to an array	of wchar_t. Bytes from
	     the array are written up to (but not including)  any  terminating
	     null  character. If the precision is specified, only that portion
	     of	the wide-character array that will display in  the  number  of
	     columns of	screen display specified by precision will be written.
	     If	the precision is not specified,	it is taken to be infinite, so
	     all  wide	characters up to the first null	character are printed.
	     An	argument with a	null value will	yield undefined	results.

       p     The  argument must	be a pointer to	void. The value	of the pointer
	     is	converted to a set of sequences	of printable characters, which
	     should be the same	as the set of sequences	that  are  matched  by
	     the %p conversion of the scanf(3C)	function.

       n     The  argument must	be a pointer to	an integer into	which is writ-
	     ten the number of bytes written to	the output standard I/O	stream
	     so	far by this call to one	of the printf()	functions. No argument
	     is	converted.

       %     Print a %;	no argument is converted. The entire conversion	speci-
	     fication must be %%.

       If  a  conversion  specification	does not match one of the above	forms,
       the behavior is undefined.

       If a floating-point value is the	internal representation	for  infinity,
       the  output  is [+-]Infinity, where Infinity is either Infinity or Inf,
       depending on the	desired	output string length.  Printing	 of  the  sign
       follows the rules described above.

       If  a  floating-point  value is the internal representation for "not-a-
       number,"	the output is [+-]NaN. Printing	of the sign follows the	 rules
       described above.

       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. Charac-
       ters generated  by  printf()  and  fprintf()  are  printed  as  if  the
       putc(3C)	function had been called.

       The  st_ctime and st_mtime fields of the	file will be marked for	update
       between the call	to a successful	execution of printf() or fprintf() and
       the next	successful completion of a call	to fflush(3C) or fclose(3C) on
       the same	stream or a call to exit(3C) or	abort(3C).

RETURN VALUES
       The printf(), fprintf(),	and sprintf() functions	return the  number  of
       bytes  transmitted  (excluding the terminating null byte	in the case of
       sprintf()).

       The snprintf() function returns the  number  of	characters  formatted,
       that  is,  the number of	characters that	would have been	written	to the
       buffer if it were large enough. If the value of n is 0  on  a  call  to
       snprintf(), an unspecified value	less than 1 is returned.

       Each  function  returns a negative value	if an output error was encoun-
       tered.

ERRORS
       For the conditions under	which printf() and fprintf() will fail and may
       fail, refer to fputc(3C)	or fputwc(3C).

       In addition, all	forms of printf() may fail if:

       EILSEQ
	     A wide-character code that	does not correspond to a valid charac-
	     ter has been detected.

       EINVAL
	     There are insufficient arguments.

       In addition, printf() and fprintf() may fail if:

       ENOMEM
	     Insufficient storage space	is available.

USAGE
       If the application calling the printf() functions has  any  objects  of
       type  wint_t  or	 wchar_t, it must also include the header <wchar.h> to
       have these objects defined.

       The sprintf() and snprintf() functions are MT-Safe in multithreaded ap-
       plications.  The	printf() and fprintf() functions can be	used safely in
       multithreaded applications, as  long  as	 setlocale(3C)	is  not	 being
       called to change	the locale.

   Escape Character Sequences
       It  is  common  to  use the following escape sequences built into the C
       language	when entering format strings for the printf()  functions,  but
       these  sequences	 are  processed	by the C compiler, not by the printf()
       function.

	      \a    Alert. Ring	the bell.

	      \b    Backspace. Move the	printing position to one character be-
		    fore  the current position,	unless the current position is
		    the	start of a line.

	      \f    Form feed. Move  the  printing  position  to  the  initial
		    printing position of the next logical page.

	      \n    Newline.  Move  the	 printing position to the start	of the
		    next line.

	      \r    Carriage return. Move the printing position	to  the	 start
		    of the current line.

	      \t    Horizontal tab. Move the printing position to the next im-
		    plementation-defined horizontal tab	position on  the  cur-
		    rent line.

	      \v    Vertical  tab.  Move the printing position to the start of
		    the	next implementation-defined vertical tab position.

	In addition, the C language supports character sequences of the	form

	      \octal-number

       and

	      \hex-number

       which translates	into the character represented by the octal  or	 hexa-
       decimal	number.	 For example, if ASCII representations are being used,
       the letter 'a' may be written as	'\141' and 'Z' as '\132'. This	syntax
       is  most	frequently used	to represent the null character	as '\0'.  This
       is exactly equivalent to	the numeric constant zero (0). Note  that  the
       octal  number does not include the zero prefix as it would for a	normal
       octal constant. To specify a hexadecimal	number,	omit the zero so  that
       the  prefix  is	an 'x' (uppercase 'X' is not allowed in	this context).
       Support for hexadecimal sequences  is  an  ANSI	extension.  See	 stan-
       dards(5).

EXAMPLES
       Example	1: To print the	language-independent date and time format, the
       following statement could be used:

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

       For 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

       Example 2: To print a date and time in the form Sunday, July 3,	10:02,
       where weekday and month are pointers to null-terminated strings:

       printf("%s, %s %i, %d:%.2d", weekday, month, day, hour, min);

       Example 3: To print pi to 5 decimal places:

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

   Default
       Example 4: The following	example	applies	only to	applications which are
       not standard-conforming (see standards(5)). To print a list of names in
       columns which are 20 characters wide:

       printf("%20s%20s%20s", lastname,	firstname, middlename);

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe with exceptions	   |
       +-----------------------------+-----------------------------+
       |CSI			     |Enabled			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       exit(2),	lseek(2), write(2), abort(3C), ecvt(3C), exit(3C), fclose(3C),
       fflush(3C), fputwc(3C), putc(3C), scanf(3C), setlocale(3C),  stdio(3C),
       wcstombs(3C), wctomb(3C), attributes(5),	environ(5), standards(5)

SunOS 5.9			  7 Oct	1999			    printf(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | EXAMPLES | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=printf&sektion=3c&manpath=SunOS+5.9>

home | help