fwprintf man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

FWPRINTF(3C)							  FWPRINTF(3C)

NAME
       fwprintf, wprintf, swprintf - print formatted wide-character output

SYNOPSIS
       #include <stdio.h>
       #include <wchar.h>

       int fwprintf(FILE *restrict stream, const wchar_t *restrict format,
	    ...);

       int wprintf(const wchar_t *restrict format, ...);

       int swprintf(wchar_t *restrict s, size_t n, const wchar_t *restrict format,
	    ...);

DESCRIPTION
       The  fwprintf() function places output on the named output stream.  The
       wprintf() function places output on the standard output stream  stdout.
       The swprintf() function places output followed by the null wide-charac‐
       ter in consecutive wide-characters starting at *s; no more than n wide-
       characters  are	written,  including a terminating null wide-character,
       which is always added (unless n is zero).

       Each of these functions converts,  formats  and	prints	its  arguments
       under  control  of the format wide-character string. The format is com‐
       posed of zero or more directives: ordinary wide-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 wide-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 pro‐
       vides for the definition of format wide-character strings  that	select
       arguments  in an order appropriate to specific languages (see the EXAM‐
       PLES section).

       In format wide-character strings containing the %n$ form of  conversion
       specifications,	numbered  arguments in the argument list can be refer‐
       enced from the format wide-character string as many times as required.

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

       All forms of the fwprintf() functions allow for the insertion of a lan‐
       guage-dependent radix character in the output string, output as a wide-
       character value. The radix character is defined in 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 (.).

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

	   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	 wide-characters  than	the  field  width,  it will be
		  padded with spaces by default 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 (*), described below, or a decimal
		  integer.

	   o	  An optional precision that gives the minimum number of  dig‐
		  its  to appear for the d, i, o, u, x, and X conversions; the
		  number of digits to appear after the radix character for the
		  a, A, e, E, f, and F conversions; the maximum number of sig‐
		  nificant digits for the g and G conversions; or the  maximum
		  number  of  wide-characters to be printed from a string in s
		  conversions.	The precision takes the form of a  period  (.)
		  followed  by	either 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 conver‐
		  sion wide-character, the behavior is undefined.

	   o	  An optional length modifier that specifies the size  of  the
		  argument.

	   o	  A  conversion	 specifier  wide  character 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 wide-character strings containing the %n$ form of  a
       conversion  specification,  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 position in the argument list (after the format
       argument) of an integer argument containing the field width  or	preci‐
       sion, for example:

	 wprintf(L"%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 wide-character string are unde‐
       fined. 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 wide-character string.

       The flag wide-characters and their meanings are:

       '
		The integer portion of the result of a decimal conversion (%i,
		%d,  %u,  %f, %F, %g, or %G) will be formatted with thousands'
		grouping wide-characters. For other conversions	 the  behavior
		is  undefined.	The  non-monetary  grouping  wide-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 negative value is converted if this flag is not specified.

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

       #
		This  flag  specifies  that the value is to be converted to an
		alternative form.  For o conversion, it increases  the	preci‐
		sion  (if necessary) to force the first digit of the result to
		be 0. For x or X conversions, a non-zero result will  have  0x
		(or  0X) prefixed to it. For a, A, e, E, f, F, g, or G conver‐
		sions, the result will always contain a radix character,  even
		if  no	digits follow it. Without this flag, a 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  normally  are.  For	 other
		conversions, the behavior is undefined.

       0
		For  d, i, o, u, x, X, a, A, e, E, f, F, g, and G conversions,
		leading zeros (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 speci‐
		fied, the 0 flag will be ignored. If the 0 and	'  flags  both
		appear,	 the grouping wide-characters are inserted before zero
		padding. For other conversions, the behavior is undefined.

       The length modifiers and their meanings:

       hh
		       Specifies that a following d, i, o, u, x, or X  conver‐
		       sion  specifier	applies	 to  a signed char or unsigned
		       char argument (the argument  will  have	been  promoted
		       according  to  the  integer  promotions,	 but its value
		       shall be converted to  signed  char  or	unsigned  char
		       before  printing);  or  that  a	following n conversion
		       specifier applies to a pointer to a signed  char	 argu‐
		       ment.

       h
		       Specifies  that a following d, i, o, u, x, or X conver‐
		       sion specifier applies to a  short  or  unsigned	 short
		       argument	 (the argument will have been promoted accord‐
		       ing to the integer promotions, but its value  shall  be
		       converted  to short or unsigned short before printing);
		       or that a following n conversion specifier applies to a
		       pointer to a short argument.

       l (ell)
		       Specifies  that a following d, i, o, u, x, or X conver‐
		       sion specifier applies to a long or unsigned long argu‐
		       ment;  that  a following n conversion specifier applies
		       to a pointer to a long argument;	 that  a  following  c
		       conversion specifier applies to a wint_t argument; that
		       a following s conversion specifier applies to a pointer
		       to  a wchar_t argument; or has no effect on a following
		       a, A, e, E, f, F, g, or G conversion specifier.

       ll (ell-ell)
		       Specifies that a following d, i, o, u, x, or X  conver‐
		       sion  specifier applies to a long long or unsigned long
		       long argument; or that a following n conversion	speci‐
		       fier applies to a pointer to a long long argument.

       j
		       Specifies  that a following d, i, o, u, x, or X conver‐
		       sion specifier applies  to  an  intmax_t	 or  uintmax_t
		       argument;  or  that  a following n conversion specifier
		       applies to a pointer to an intmax_t argument.

       z
		       Specifies that a following d, i, o, u, x, or X  conver‐
		       sion specifier applies to a size_t or the corresponding
		       signed integer type argument; or	 that  a  following  n
		       conversion  specifier  applies to a pointer to a signed
		       integer type corresponding to size_t argument.

       t
		       Specifies that a following d, i, o, u, x, or X  conver‐
		       sion  specifier	applies	 to  a ptrdiff_t or the corre‐
		       sponding unsigned type argument; or that a following  n
		       conversion   specifier	applies	 to  a	pointer	 to  a
		       ptrdiff_t argument.

       L
		       Specifies that a following a, A, e, E, f, F,  g,	 or  G
		       conversion specifier applies to a long double argument.

       If  a  length modifier appears with any conversion specifier other than
       as specified above, the behavior is undefined.

       The conversion wide-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 precision is 1. The result  of  converting  0  with  an
	       explicit precision of 0 is no wide-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 repre‐
	       sented 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 wide-characters.

       u
	       The unsigned int argument is converted to unsigned decimal for‐
	       mat in the style dddd. The precision specifies the minimum num‐
	       ber 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 wide-characters.

       x
	       The  unsigned int argument is converted to unsigned hexadecimal
	       format in the style dddd; the letters abcdef are used. The pre‐
	       cision 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 wide-characters.

       X
	       Behaves the same as the x conversion wide-character except that
	       letters "ABCDEF" are used instead of "abcdef".

       f, 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	speci‐
	       fication.  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 converted value  is  rounded  to
	       fit  the	 specified  output  format according to the prevailing
	       floating point rounding direction mode. If  the	conversion  is
	       not exact, an inexact exception is raised.

	       For the f specifier, a double argument representing an infinity
	       or NaN is converted in the style of the e conversion specifier,
	       except  that for an infinite argument, "infinity" or "Infinity"
	       is printed when the precision is at least 8 and "inf" or	 "Inf"
	       is printed otherwise.

	       For the F specifier, a double argument representing an infinity
	       or NaN is converted in the SUSv3	 style	of  the	 E  conversion
	       specifier,  except that for an infinite argument, "INFINITY" is
	       printed when the precision is  at  least	 8  and	 or  "INF"  is
	       printed otherwise.

       e, E
	       The  double  argument  is  converted in 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; if the precision  is	 miss‐
	       ing,  it	 is taken as 6; if the precision is 0 and no # flag is
	       present, no radix character appears.  The  converted  value  is
	       rounded	to  fit	 the  specified output format according to the
	       prevailing floating point rounding direction mode. If the  con‐
	       version	is  not	 exact,	 an inexact exception is raised. The E
	       conversion wide-character will produce a number with E  instead
	       of  e introducing the exponent. The exponent always contains at
	       least two digits. If the value is 0, the exponent is 0.

	       Infinity and NaN values are handled in  one  of	the  following
	       ways:

	       SUSv3
			  For  the e specifier, a double argument representing
			  an infinity is printed as  "[−]infinity",  when  the
			  precision  for  the  conversion is at least 7 and as
			  "[−]inf" otherwise. A double argument representing a
			  NaN  is  printed  as	"[−]nan". For the E specifier,
			  "INF", "INFINITY", and "NAN" are printed instead  of
			  "inf", "infinity", and "nan", respectively. Printing
			  of the sign follows the rules described above.

	       Default
			  A  double  argument  representing  an	 infinity   is
			  printed as "[−]Infinity", when the precision for the
			  conversion is at least 7 and as "[−]Inf"  otherwise.
			  A  double  argument representing a NaN is printed as
			  "[−]NaN". Printing of the  sign  follows  the	 rules
			  described above.

       g, G
	       The double argument is converted in the style f or e (or in the
	       style E in the case of a G conversion wide-character), with the
	       precision  specifying  the  number of significant digits. If an
	       explicit precision is 0, it is  taken  as  1.  The  style  used
	       depends	on  the	 value converted; style e (or E ) will be used
	       only if the exponent resulting from such a conversion  is  less
	       than  −4	 or  greater than or equal to the precision.  Trailing
	       zeros are removed from the fractional portion of the result;  a
	       radix character appears only if it is followed by a digit.

	       A  double argument representing an infinity or NaN is converted
	       in the style of the e or E conversion  specifier,  except  that
	       for an infinite argument, "infinity", "INFINITY", or "Infinity"
	       is printed when the precision is at least 8 and	"inf",	"INF",
	       or "Inf" is printed otherwise.

       a, A
	       A  double argument representing a floating-point number is con‐
	       verted in the style "[-]0xh.hhhhp±d", where the single hexadec‐
	       imal  digit  preceding  the  radix point is 0 if the value con‐
	       verted is zero and 1 otherwise and the  number  of  hexadecimal
	       digits after it are equal to the precision; if the precision is
	       missing, the number of digits printed after the radix point  is
	       13  for the conversion of a double value, 16 for the conversion
	       of a long double value on x86, and 28 for the conversion	 of  a
	       long  double  value  on SPARC; if the precision is zero and the
	       '#' flag is not	specified,  no	decimal-point  wide  character
	       appears. The letters "abcdef" are used for a conversion and the
	       letters "ABCDEF" for A conversion. The A	 conversion  specifier
	       produces	 a number with 'X' and 'P' instead of 'x' and 'p'. The
	       exponent always contains at least one digit, and only  as  many
	       more  digits  as necessary to represent the decimal exponent of
	       2. If the value is zero, the exponent is zero.

	       The converted valueis rounded to fit the specified output  for‐
	       mat  according to the prevailing floating point rounding direc‐
	       tion mode. If the conversion is not exact, an inexact exception
	       is raised.

	       A  double argument representing an infinity or NaN is converted
	       in the SUSv3 style of an e or E conversion specifier.

       c
	       If no l (ell) qualifier is present, the int  argument  is  con‐
	       verted to a wide-character as if by calling the btowc(3C) func‐
	       tion and the resulting wide-character is written. Otherwise the
	       wint_t argument is converted to wchar_t, and written.

       s
	       If  no  l  (ell)	 qualifier  is present, the argument must be a
	       pointer to a character array containing	a  character  sequence
	       beginning in the initial shift state. Characters from the array
	       are converted as if by repeated calls to the mbrtowc(3C)	 func‐
	       tion,  with  the	 conversion  state  described  by an mbstate_t
	       object initialized to zero before the first character  is  con‐
	       verted,	and  written up to (but not including) the terminating
	       null wide-character. If the precision  is  specified,  no  more
	       than that many wide-characters are written. If the precision is
	       not specified or is greater than the size  of  the  array,  the
	       array must contain a null wide-character.

	       If  an  l  (ell)	 qualifier  is present, the argument must be a
	       pointer to an array of type wchar_t. Wide characters  from  the
	       array  are written up to (but not including) a terminating null
	       wide-character. If no precision is specified or is greater than
	       the size of the array, the array must contain a null wide-char‐
	       acter. If a precision is specified,  no	more  than  that  many
	       wide-characters are written.

       p
	       The  argument  must  be	a  pointer  to	void. The value of the
	       pointer is converted to a sequence  of  printable  wide-charac‐
	       ters.

       n
	       The  argument  must  be	a  pointer to an integer into which is
	       written the number of wide-characters written to the output  so
	       far  by	this call to one of the fwprintf() functions. No argu‐
	       ment is converted.

       C
	       Same as lc.

       S
	       Same as ls.

       %
	       Output a % wide-character; no argument is converted. The entire
	       conversion specification must be %%.

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

       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 fwprintf() and wprintf() are printed as if fputwc(3C)
       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 fwprintf() or wprintf()
       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
       Upon  successful completion, these functions return the number of wide-
       characters transmitted excluding the terminating null wide-character in
       the  case  of  swprintf()  or  a	 negative value if an output error was
       encountered.

       If n or more wide characters were requested to be  written,  swprintf()
       returns a negative value.

ERRORS
       For  the	 conditions under which fwprintf() and wprintf() will fail and
       may fail, refer to fputwc(3C).

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

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

       EINVAL
		 There are insufficient arguments.

       In addition, wprintf() and fwprintf() may fail if:

       ENOMEM
		 Insufficient storage space is available.

EXAMPLES
       Example 1 Print Language-dependent Date and Time Format.

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

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

       For American usage, format could be a  pointer  to  the	wide-character
       string:

	 L"%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 wide-charac‐
       ter string:

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

       producing the message:

	 Sonntag, 3. Juli, 10:02

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

       ┌────────────────────┬─────────────────────────┐
       │  ATTRIBUTE TYPE    │	  ATTRIBUTE VALUE     │
       ├────────────────────┼─────────────────────────┤
       │Interface Stability │ Standard		      │
       ├────────────────────┼─────────────────────────┤
       │MT-Level	    │ MT-Safe with exceptions │
       └────────────────────┴─────────────────────────┘

SEE ALSO
       btowc(3C),   fputwc(3C),	  fwscanf(3C),	 mbrtowc(3C),	setlocale(3C),
       attributes(5), standards(5)

NOTES
       The  fwprintf(), wprintf(), and swprintf() functions can be used safely
       in multithreaded applications, as long as setlocale(3C)	is  not	 being
       called to change the locale.

       If  the	j  length modifier is used, 32-bit applications that were com‐
       piled using c89 on releases prior to Solaris 10 will  experience	 unde‐
       fined behavior.

				  Nov 1, 2003			  FWPRINTF(3C)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net