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

FreeBSD Manual Pages

  
 
  

home | help
printf(3S)							    printf(3S)

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

SYNOPSIS
DESCRIPTION
       places output on	the standard output stream stdout.

       places output on	the named output stream.

       places  ``output'', followed by the null	character in consecutive bytes
       starting	at It is the user's responsibility to ensure that enough stor-
       age is available.

       behaves	like except that it limits the number of characters written to
       the destination buffer to maxsize, including the	terminating null char-
       acter.

       Each  function  converts, formats, and prints its args under control of
       the format.  format is a	character string containing two	types  of  ob-
       jects:  plain characters	that are copied	to the output stream, and con-
       version specifications, each of which results in	fetching zero or  more
       args.  The results are undefined	if there are insufficient args for the
       format.	If the format is exhausted while args remain, excess args  are
       ignored.

       Each conversion specification is	introduced by the character or where n
       is a decimal integer in the range 1 through is defined in The construc-
       tion  indicates that this conversion should be applied to the nth argu-
       ment, rather than to the	next unused one.

       An argument can be referenced by	a specification	more than  once.   The
       two  forms  of  introducing  a  conversion specification, and cannot be
       mixed within a single format string.  When numbered argument specifica-
       tions are used, specifying the Nth argument requires that all the lead-
       ing arguments, from the first to	the (N-1)th, are specified in the for-
       mat  string.   The  results  of mixing numbered and unnumbered argument
       specifications in a format string are undefined.

       After the or the	following appear in sequence:

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

	      2.   An  optional	 string	of decimal digits to specify a minimum
		   field width in bytes.  If the  converted  value  has	 fewer
		   characters  than  the  field	 width,	it is be padded	on the
		   left	(or right, if the left-adjustment flag	described  be-
		   low,	 has  been  given)  to	the field width.  If the field
		   width is preceded by	a zero,	the string is  right  adjusted
		   with	 zero-padding  on the left (see	the leading-zero flag,
		   described below).

	      3.   A precision that gives the minimum number of	digits to  ap-
		   pear	for the	or conversions,	the number of digits to	appear
		   after the radix character for the and conversions, the max-
		   imum	 number	 of  significant digits	for the	conversion, or
		   the maximum number of bytes to be printed from a string  in
		   the	conversion.   The precision takes the form of a	period
		   followed by a decimal digit string; a null digit string  is
		   treated as zero.

	      4.   An optional (the letter ``ell''), specifying	that a follow-
		   ing or conversion character applies to a long integer  arg;
		   an  optional	specifying that	a following conversion charac-
		   ter applies to a pointer to a long integer arg; an optional
		   specifying that a following or conversion character applies
		   to a	short integer arg; an optional specifying that a  fol-
		   lowing or conversion	wide-character applies to a type which
		   is the 80-bit IEEE-754 double-extended type in the  Itanium
		   architecture;  an  optional	specifying that	a following or
		   conversion character	applies	to a long long integer arg; an
		   optional  specifying	 that a	following conversion character
		   applies to a	pointer	to a short integer  arg;  an  optional
		   specifying that a following or conversion character applies
		   to a	long double arg.  An or	before	any  other  conversion
		   character is	ignored.

	      5.   A  conversion  character that indicates the type of conver-
		   sion	to be applied.

       A field width or	precision can 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 pre-
       cision, or both must appear in that order before	the arg, 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	preci-
       sion were omitted.  Format strings containing conversion	specifications
       can also	indicate a field width or precision by the sequence The	n  in-
       dicates	the  position of an integer arg	.  With	the sequence, the args
       specifying field	width or precision can appear before or	after the  arg
       to be converted.

       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.   Thousands'  grouping  and	 the separator
			character are determined by the	"grouping" and	"thou-
			sands_sep"  fields  of the LC_NUMERIC category respec-
			tively.	(See localedef(4)).  For other conversions the
			behavior is undefined.	The nonmonetary	grouping char-
			acter is used.

	      The resulting conversion is left-justified within	the field.

	      The resulting signed conversion always begins with a sign
			or

	      blank	If the first character of a signed conversion is not a
			sign, a	blank is prefixed to the result.  This implies
			that if	the blank and flags  both  appear,  the	 blank
			flag is	ignored.

	      This  flag  specifies that the value is converted	to an ``alter-
	      nate form''.
			For and	conversions, the flag has no effect.  For con-
			version, it increases the precision to force the first
			digit of the result to be a zero.  For or  conversion,
			a nonzero result is prefixed by	or For a conversion, a
			nonzero	result is prefixed by For and conversions, the
			result	always	contains a radix character, even if no
			digits follow the radix.  (Normally, a radix character
			appears	 in the	resulting conversions only if followed
			by a digit).  For and conversions, trailing zeros  are
			removed	from the result	(which they normally are).

	      Leading zeros (following any indication of sign or base)
			are  used to pad to the	field width for	all conversion
			characters.  No	space padding is performed.   If  both
			the  and appear, the flag is ignored.  For and conver-
			sions, if a precision is specified, the	 flag  is  ig-
			nored.

       The conversion characters and their meanings are:

	      The integer    arg  is converted to signed decimal and are iden-
			     tical), unsigned octal decimal or hexadecimal no-
			     tation and	respectively; the letters are used for
			     conversion	and the	letters	for  conversion.   The
			     precision	specifies the minimum number of	digits
			     to	appear.	 If the	value being converted  can  be
			     represented  in fewer digits, it is expanded with
			     leading zeros.   (For  compatibility  with	 older
			     versions, padding with leading zeros can alterna-
			     tively be specified by inserting a	zero in	 front
			     of	the field width.  This does not	imply an octal
			     value for the field width).  The  default	preci-
			     sion is 1.	 The result of converting a zero value
			     with a precision of zero is a null	string.

	      The double     arg is converted to decimal notation in the style
			     where  r  is  the radix character.	 The number of
			     digits after the radix character is equal to  the
			     precision	specification.	 If  the  precision is
			     missing, six digits are output.  If the precision
			     is	explicitly zero, no radix character appears.

	      The double     arg  is converted in the style where is the radix
			     character.	 There is one digit before  the	 radix
			     character	and  the  number of digits after it is
			     equal to the precision;  when  the	 precision  is
			     missing,  six  digits are produced; if the	preci-
			     sion is zero, no radix  character	appears.   The
			     format code produces a number with	instead	of in-
			     troducing the exponent.  The exponent always con-
			     tains at least two	digits.

	      The double     arg  is  printed  in style	or (or in style	in the
			     case of a format code), with the precision	speci-
			     fying  the	 number	 of  significant  digits.  The
			     style used	depends	on the value converted:	 style
			     is	 used  only if the exponent resulting from the
			     conversion	is less	than 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 followed by a
			     digit.

	      For IPF only.  The double	arg is converted in the	style where is
			     the  radix	 character.  There is one digit	before
			     the radix character and the number	of digits  af-
			     ter it is equal to	the precision; when the	preci-
			     sion is missing, 13 digits	are  produced  for  15
			     for  and 28 for (which is sufficient for an exact
			     representation of the value); if the precision is
			     0,	 no  radix character appears.  The letters are
			     used for conversion and the letters  for  conver-
			     sion.  The	converison specifier produces a	number
			     with and instead of and The exponent always  con-
			     tains  at	least one digit, and only as many more
			     digits as necessary to represent the decimal  ex-
			     ponent  of	2.  If the value is zero, the exponent
			     is	zero.

	      The integer    arg is converted to an unsigned char, and the re-
			     sulting character is printed.  If an (ell)	quali-
			     fier is present, the arg is converted to an array
			     of	 bytes	representing the single	wide character
			     according to the setting of Resulting  bytes  are
			     printed.	If  the	 field	width  would otherwise
			     cause the wide character to be  split,  the  wide
			     character	is  printed and	the field width	is ad-
			     justed upward.

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

	      Same as

	      The	     arg is taken to be	a string  (character  pointer)
			     and  characters from the string are printed until
			     a null character is encountered or	the number  of
			     bytes indicated by	the precision specification is
			     reached.  If the  precision  is  missing,	it  is
			     taken to be infinite, so all characters up	to the
			     first null	character are printed.	A  NULL	 value
			     for arg yields undefined results.

			     If	 an  (ell)  qualifier is present, the argument
			     must be a pointer to an array of type  Wide-char-
			     acters from the array are converted to characters
			     (each as if by a call to the function,  with  the
			     conversion	 state described by an object initial-
			     ized to zero before the first  wide-character  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 precision is	specified, the array must con-
			     tain  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 character 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.

	      Same as

	      The value	of a pointer to	void
			     arg is printed as a sequence of unsigned hexadec-
			     imal numbers.  The	precision specifies the	 mini-
			     mum number	of digits to appear.  If the value be-
			     ing converted can be represented in fewer digits,
			     it	 is  expanded with leading zeros.  The default
			     precision is 1.  The result of converting a  zero
			     value with	a precision of zero is a null string.

	      A	pointer	to an integer
			     arg  is  expected.	 This pointer is used to store
			     the number	of bytes printed on the	output	stream
			     so	far by this call to the	function.  No argument
			     is	converted.

	      Print a	     no	argument is converted.	The entire  conversion
			     specification must	be

       In  no case does	a nonexistent 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.

       The and conversions will	print for infinity and for both	quiet and sig-
       naling values.

       The and conversions will	print for infinity and for both	quiet and sig-
       naling  values.	 There will be a new conversion	specifier that will be
       identical to the	conversion specifier except that it will print	infin-
       ity and NaN as respectively, and

       For  and	 conversions  (for  IPF),  the value is	correctly rounded to a
       hexadecimal floating point number with the given	precision.

       The and converions on IPF  round	 according  to	the  specification  in
       ISO/IEC C99: if the number of significant decimal digits	is at most 36,
       then the	result is correctly rounded.

       Characters generated by and are printed as  if  had  been  called  (see
       putc(3S)).

APPLICATION USAGE
       To  use	functionality, the flag	must be	passed as a compiler option or
       defined as a macro in source files.

       After or	is applied to a	stream,	the stream becomes byte-oriented  (see
       orientation(5)).

EXTERNAL INFLUENCES
   Locale
       The category affects the	following features:

	      o	 Plain	characters  within  format  strings are	interpreted as
		 single	byte and/or multibyte characters.

	      o	 Field width is	given in terms of bytes.   As  characters  are
		 placed	 on  the output	stream,	they are interpreted as	single
		 byte or multibyte characters and the field  width  is	decre-
		 mented	by the length of the character.

	      o	 Precision  is	given  in  terms  of bytes.  As	characters are
		 placed	on the output stream, they are interpreted  as	single
		 byte or multibyte characters and the precision	is decremented
		 by the	length of the character.

	      o	 The return value is given in terms of bytes.	As  characters
		 are placed on the output stream, they are interpreted as sin-
		 gle byte or multibyte characters  and	the  byte  count  that
		 makes up the return value is incremented by the length	of the
		 character.

       The category determines the radix character  used  to  print  floating-
       point  numbers,	and the	thousands' grouping characters if the grouping
       flag is on.

   International Code Set Support
       Single byte character code sets	are  supported.	  Multibyte  character
       code sets are also supported as described in the	category above.

RETURN VALUE
       Each function returns the number	of bytes transmitted (excluding	the in
       the case	of or a	negative value if an output error was encountered.

ERRORS
       and fail	if either the stream is	unbuffered or stream's	buffer	needed
       to  be flushed causing an underlying call to be invoked (see write(2)),
       and:

	      [EAGAIN]	     The flag is set for the file descriptor  underly-
			     ing  stream  and  the process would be delayed in
			     the write operation.

	      [EBADF]	     The file descriptor underlying stream  is	not  a
			     valid file	descriptor open	for writing.

	      [EFBIG]	     An	 attempt  was made to write to a file that ex-
			     ceeds the process's file size limit or the	 maxi-
			     mum file size (see	ulimit(2)).

	      [EINTR]	     A signal was caught during	the system call.

	      [EIO]	     The  process is in	a background process group and
			     is	attempting to write to its controlling	termi-
			     nal,  is set, the process is neither ignoring nor
			     blocking the signal, and the process group	of the
			     process is	orphaned.

	      [ENOSPC]	     There  was	 no free space remaining on the	device
			     containing	the file.

	      [EPIPE]	     An	attempt	is made	to write to  a	pipe  or  FIFO
			     that  is  not open	for reading by any process.  A
			     signal is also sent to the	process.

	      [EILSEQ]	     The data obtained from the	input stream does  not
			     form a valid wide character.

	      [ENOMEM]	     Insufficient storage space	is available.

       Additional values can be	set by the underlying function (see write(2)).

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

       To print	pi to 5	decimal	places:

       To create a language independent	date-and-time printing routine write:

       For American usage, format would	point to the string:

       and result in the output:

       For German usage, the string:

       results in the output:

WARNINGS
       Notice that with	the conversion character, an int arg is	 converted  to
       an  unsigned char.  Hence, whole	multibyte characters cannot be printed
       using a single conversion character.

       A precision with	the conversion character might result in  the  trunca-
       tion of a multibyte character.

       Use  of a conversion character which doesn't match the type of the cor-
       responding argument passed in will result in  invalid  data  being  re-
       turned.	 For  example,	the modifying specifying that the following or
       conversion character applies to a long long integer arg,	 is  necessary
       for proper results when the argument is a long long integer.

AUTHOR
       and were	developed by AT&T and HP.

SEE ALSO
       ecvt(3C),  ltostr(3C),  setlocale(3C),  putc(3S), scanf(3S), stdio(3S),
       orientation(5), thread_safety(5).

STANDARDS CONFORMANCE
								    printf(3S)

NAME | SYNOPSIS | DESCRIPTION | APPLICATION USAGE | EXTERNAL INFLUENCES | RETURN VALUE | ERRORS | EXAMPLES | WARNINGS | AUTHOR | SEE ALSO | STANDARDS CONFORMANCE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=printf&sektion=3s&manpath=HP-UX+11.22>

home | help