fwprintf.3p (26282B)
- '\" et
- .TH FWPRINTF "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
- .\"
- .SH PROLOG
- This manual page is part of the POSIX Programmer's Manual.
- The Linux implementation of this interface may differ (consult
- the corresponding Linux manual page for details of Linux behavior),
- or the interface may not be implemented on Linux.
- .\"
- .SH NAME
- fwprintf,
- swprintf,
- wprintf
- \(em print formatted wide-character output
- .SH SYNOPSIS
- .LP
- .nf
- #include <stdio.h>
- #include <wchar.h>
- .P
- int fwprintf(FILE *restrict \fIstream\fP, const wchar_t *restrict \fIformat\fP, ...);
- int swprintf(wchar_t *restrict \fIws\fP, size_t \fIn\fP,
- const wchar_t *restrict \fIformat\fP, ...);
- int wprintf(const wchar_t *restrict \fIformat\fP, ...);
- .fi
- .SH DESCRIPTION
- The functionality described on this reference page is aligned with the
- ISO\ C standard. Any conflict between the requirements described here and the
- ISO\ C standard is unintentional. This volume of POSIX.1\(hy2017 defers to the ISO\ C standard.
- .P
- The
- \fIfwprintf\fR()
- function shall place output on the named output
- .IR stream .
- The
- \fIwprintf\fR()
- function shall place output on the standard output stream
- .IR stdout .
- The
- \fIswprintf\fR()
- function shall place output followed by the null wide character in
- consecutive wide characters starting at *\fIws\fP; no more than
- .IR n
- wide characters shall be written, including a terminating null wide
- character, which is always added (unless
- .IR n
- is zero).
- .P
- Each of these functions shall convert, format, and print its arguments
- under control of the
- .IR format
- wide-character string. The
- .IR format
- is composed of zero or more directives:
- .IR "ordinary wide-characters" ,
- which are simply copied to the output stream, and
- .IR "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
- .IR format .
- If the
- .IR format
- is exhausted while arguments remain, the excess arguments are evaluated
- but are otherwise ignored.
- .P
- Conversions can be applied to the
- .IR n th
- argument after the
- .IR format
- in the argument list, rather than to the next unused argument. In this
- case, the conversion specifier wide character
- .BR %
- (see below) is replaced by the
- sequence
- .BR \(dq%n$\(dq ,
- where
- .IR 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
- .IR format
- wide-character strings that select arguments in an order appropriate to
- specific languages (see the EXAMPLES section).
- .P
- The
- .IR format
- can contain either numbered argument specifications (that is,
- \fR"%\fIn\fR$"\fR and \fR"*\fIm\fR$"\fR), or unnumbered argument
- conversion specifications (that is,
- .BR %
- and
- .BR * ),
- but not both. The only exception to this is that
- .BR %%
- can be mixed with the \fR"%\fIn\fR$"\fR form. The results of mixing
- numbered and unnumbered argument specifications in a
- .IR format
- wide-character string are undefined. When numbered argument
- specifications are used, specifying the
- .IR N th
- argument requires that all the leading arguments, from the first to the
- (\fIN\fP\-1)th, are specified in the
- .IR format
- wide-character string.
- .P
- In
- .IR format
- wide-character strings containing the \fR"%\fIn\fR$"\fR form of
- conversion specification, numbered arguments in the argument list can
- be referenced from the
- .IR format
- wide-character string as many times as required.
- .P
- In
- .IR format
- wide-character strings containing the
- .BR %
- form of conversion specification, each argument in the argument list
- shall be used exactly once. It is unspecified whether an encoding
- error occurs if the format string contains
- .BR wchar_t
- values that do not correspond to members of the character
- set of the current locale and the specified semantics do not
- require that value to be processed by
- \fIwcrtomb\fR().
- .P
- All forms of the
- \fIfwprintf\fR()
- function allow for the insertion of a locale-dependent radix
- character in the output string, output as a wide-character value. The
- radix character is defined in the current locale (category
- .IR LC_NUMERIC ).
- In the POSIX locale, or in a locale where the radix character is not
- defined, the radix character shall default to a
- <period>
- (\c
- .BR '.' ).
- .br
- .P
- Each conversion specification is introduced by the
- .BR '%'
- wide character
- or by the wide-character sequence \fR"%\fIn\fR$"\fR,
- after which the following appear in sequence:
- .IP " *" 4
- Zero or more
- .IR flags
- (in any order), which modify the meaning of the conversion
- specification.
- .IP " *" 4
- An optional minimum
- .IR "field width" .
- If the converted value has fewer wide characters than the field width,
- it shall be padded with
- <space>
- characters by default on the left; it shall be padded on the right,
- if the left-adjustment flag (\c
- .BR '\-' ),
- described below, is given to the field width. The field width takes the
- form of an
- <asterisk>
- (\c
- .BR '*' ),
- described below, or a decimal integer.
- .IP " *" 4
- An optional
- .IR precision
- that gives the minimum number of digits to appear for the
- .BR d ,
- .BR i ,
- .BR o ,
- .BR u ,
- .BR x ,
- and
- .BR X
- conversion specifiers; the number of digits to appear after the radix
- character for the
- .BR a ,
- .BR A ,
- .BR e ,
- .BR E ,
- .BR f ,
- and
- .BR F
- conversion specifiers; the maximum number of significant digits for the
- .BR g
- and
- .BR G
- conversion specifiers; or the maximum number of wide characters to be
- printed from a string in the
- .BR s
- conversion specifiers. The precision takes the form of a
- <period>
- (\c
- .BR '.' )
- followed either by an
- <asterisk>
- (\c
- .BR '*' ),
- 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 wide character, the behavior is undefined.
- .IP " *" 4
- An optional length modifier that specifies the size of the argument.
- .IP " *" 4
- A
- .IR "conversion specifier"
- wide character that indicates the type of conversion to be applied.
- .P
- A field width, or precision, or both, may be indicated by an
- <asterisk>
- (\c
- .BR '*' ).
- In this case an argument of type
- .BR int
- supplies the field width or precision. Applications shall ensure that
- arguments specifying field width, or precision, or both appear in that
- order before the argument, if any, to be converted. A negative field
- width is taken as a
- .BR '\-'
- flag followed by a positive field width. A negative precision is taken
- as if the precision were omitted.
- In
- .IR format
- wide-character strings containing the \fR"%\fIn\fR$"\fR form
- of a conversion specification, a field width or precision may be
- indicated by the sequence \fR"*\fIm\fR$"\fR, where
- .IR m
- is a decimal integer in the range [1,{NL_ARGMAX}] giving the position
- in the argument list (after the
- .IR format
- argument) of an integer argument containing the field width or
- precision, for example:
- .sp
- .RS 4
- .nf
- wprintf(L"%1$d:%2$.*3$d:%4$.*3$d\en", hour, min, precision, sec); \*?
- .fi
- .P
- .RE
- .P
- The flag wide characters and their meanings are:
- .IP "\fR\(aq\fR" 8
- (The
- <apostrophe>.)
- The integer portion of the result of a decimal conversion (\c
- .BR %i ,
- .BR %d ,
- .BR %u ,
- .BR %f ,
- .BR %F ,
- .BR %g ,
- or
- .BR %G )
- shall be formatted with thousands' grouping wide characters. For other
- conversions, the behavior is undefined. The numeric grouping wide
- character is used.
- .IP "\fR\-\fR" 8
- The result of the conversion shall be left-justified within the field.
- The conversion shall be right-justified if this flag is not specified.
- .IP "\fR+\fR" 8
- The result of a signed conversion shall always begin with a sign (\c
- .BR '+'
- or
- .BR '\-' ).
- The conversion shall begin with a sign only when a negative value is
- converted if this flag is not specified.
- .IP <space> 8
- 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>
- shall be prefixed to the result. This means that if the
- <space>
- and
- .BR '+'
- flags both appear, the
- <space>
- flag shall be ignored.
- .IP "\fR#\fR" 8
- Specifies that the value is to be converted to an alternative form.
- For
- .BR o
- conversion, it shall increase the precision, if and only if necessary,
- to force the first digit of the result to be zero (if the value
- and precision are both 0, a single 0 is printed). For
- .BR x
- or
- .BR X
- conversion specifiers, a non-zero result shall have 0x (or 0X) prefixed
- to it. For
- .BR a ,
- .BR A ,
- .BR e ,
- .BR E ,
- .BR f ,
- .BR F ,
- .BR g ,
- and
- .BR G
- conversion specifiers, the result shall 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
- .BR g
- and
- .BR G
- conversion specifiers, trailing zeros shall
- .IR not
- be removed from the result as they normally are. For other conversion
- specifiers, the behavior is undefined.
- .IP "\fR0\fR" 8
- For
- .BR d ,
- .BR i ,
- .BR o ,
- .BR u ,
- .BR x ,
- .BR X ,
- .BR a ,
- .BR A ,
- .BR e ,
- .BR E ,
- .BR f ,
- .BR F ,
- .BR g ,
- and
- .BR G
- conversion specifiers, leading zeros (following any indication of sign
- or base) are used to pad to the field width rather than performing
- space padding, except when converting an infinity or NaN. If the
- .BR '0'
- and
- .BR '\-'
- flags both appear, the
- .BR '0'
- flag shall be ignored. For
- .BR d ,
- .BR i ,
- .BR o ,
- .BR u ,
- .BR x ,
- and
- .BR X
- conversion specifiers, if a precision is specified, the
- .BR '0'
- flag shall be ignored.
- If the
- .BR '0'
- and
- <apostrophe>
- flags both appear, the grouping wide characters are inserted before
- zero padding. For other conversions, the behavior is undefined.
- .P
- The length modifiers and their meanings are:
- .IP "\fRhh\fR" 8
- Specifies that a following
- .BR d ,
- .BR i ,
- .BR o ,
- .BR u ,
- .BR x ,
- or
- .BR X
- conversion specifier applies to a
- .BR "signed char"
- or
- .BR "unsigned char"
- argument (the argument will have been promoted according to the integer
- promotions, but its value shall be converted to
- .BR "signed char"
- or
- .BR "unsigned char"
- before printing); or that a following
- .BR n
- conversion specifier applies to a pointer to a
- .BR "signed char"
- argument.
- .IP "\fRh\fR" 8
- Specifies that a following
- .BR d ,
- .BR i ,
- .BR o ,
- .BR u ,
- .BR x ,
- or
- .BR X
- conversion specifier applies to a
- .BR "short"
- or
- .BR "unsigned short"
- argument (the argument will have been promoted according to the integer
- promotions, but its value shall be converted to
- .BR "short"
- or
- .BR "unsigned short"
- before printing); or that a following
- .BR n
- conversion specifier applies to a pointer to a
- .BR "short"
- argument.
- .IP "\fRl\fR\ (ell)" 8
- Specifies that a following
- .BR d ,
- .BR i ,
- .BR o ,
- .BR u ,
- .BR x ,
- or
- .BR X
- conversion specifier applies to a
- .BR "long"
- or
- .BR "unsigned long"
- argument; that a following
- .BR n
- conversion specifier applies to a pointer to a
- .BR "long"
- argument; that a following
- .BR c
- conversion specifier applies to a
- .BR wint_t
- argument; that a following
- .BR s
- conversion specifier applies to a pointer to a
- .BR wchar_t
- argument; or has no effect on a following
- .BR a ,
- .BR A ,
- .BR e ,
- .BR E ,
- .BR f ,
- .BR F ,
- .BR g ,
- or
- .BR G
- conversion specifier.
- .IP "\fRll\fR\ (ell-ell)" 8
- .br
- Specifies that a following
- .BR d ,
- .BR i ,
- .BR o ,
- .BR u ,
- .BR x ,
- or
- .BR X
- conversion specifier applies to a
- .BR "long long"
- or
- .BR "unsigned long long"
- argument; or that a following
- .BR n
- conversion specifier applies to a pointer to a
- .BR "long long"
- argument.
- .IP "\fRj\fR" 8
- Specifies that a following
- .BR d ,
- .BR i ,
- .BR o ,
- .BR u ,
- .BR x ,
- or
- .BR X
- conversion specifier applies to an
- .BR intmax_t
- or
- .BR uintmax_t
- argument; or that a following
- .BR n
- conversion specifier applies to a pointer to an
- .BR intmax_t
- argument.
- .IP "\fRz\fR" 8
- Specifies that a following
- .BR d ,
- .BR i ,
- .BR o ,
- .BR u ,
- .BR x ,
- or
- .BR X
- conversion specifier applies to a
- .BR size_t
- or the corresponding signed integer type argument; or that a following
- .BR n
- conversion specifier applies to a pointer to a signed integer type
- corresponding to a
- .BR size_t
- argument.
- .IP "\fRt\fR" 8
- Specifies that a following
- .BR d ,
- .BR i ,
- .BR o ,
- .BR u ,
- .BR x ,
- or
- .BR X
- conversion specifier applies to a
- .BR ptrdiff_t
- or the corresponding
- .BR unsigned
- type argument; or that a following
- .BR n
- conversion specifier applies to a pointer to a
- .BR ptrdiff_t
- argument.
- .IP "\fRL\fR" 8
- Specifies that a following
- .BR a ,
- .BR A ,
- .BR e ,
- .BR E ,
- .BR f ,
- .BR F ,
- .BR g ,
- or
- .BR G
- conversion specifier applies to a
- .BR "long double"
- argument.
- .br
- .P
- If a length modifier appears with any conversion specifier other than
- as specified above, the behavior is undefined.
- .P
- The conversion specifiers and their meanings are:
- .IP "\fRd\fR,\ \fRi\fR" 8
- The
- .BR int
- argument shall be converted to a signed decimal in the style
- \fR"[\-]\fIdddd"\fR. The precision specifies the minimum number of
- digits to appear; if the value being converted can be represented in
- fewer digits, it shall be expanded with leading zeros. The default
- precision shall be 1. The result of converting zero with an explicit
- precision of zero shall be no wide characters.
- .IP "\fRo\fP" 8
- The
- .BR unsigned
- argument shall be converted to unsigned octal format in the style
- .BR \(dqdddd\(dq .
- The precision specifies the minimum number of digits to appear; if the
- value being converted can be represented in fewer digits, it shall be
- expanded with leading zeros. The default precision shall be 1. The
- result of converting zero with an explicit precision of zero shall be
- no wide characters.
- .IP "\fRu\fP" 8
- The
- .BR unsigned
- argument shall be converted to unsigned decimal format in the style
- .BR \(dqdddd\(dq .
- The precision specifies the minimum number of digits to appear; if the
- value being converted can be represented in fewer digits, it shall be
- expanded with leading zeros. The default precision shall be 1. The
- result of converting zero with an explicit precision of zero shall be
- no wide characters.
- .IP "\fRx\fP" 8
- The
- .BR unsigned
- argument shall be converted to unsigned hexadecimal format in the style
- .BR \(dqdddd\(dq ;
- the letters
- .BR \(dqabcdef\(dq
- are used. The precision specifies the minimum number of digits to
- appear; if the value being converted can be represented in fewer
- digits, it shall be expanded with leading zeros. The default precision
- shall be 1. The result of converting zero with an explicit precision of
- zero shall be no wide characters.
- .IP "\fRX\fP" 8
- Equivalent to the
- .BR x
- conversion specifier, except that letters
- .BR \(dqABCDEF\(dq
- are used instead of
- .BR \(dqabcdef\(dq .
- .IP "\fRf\fR,\ \fRF\fR" 8
- The
- .BR double
- argument shall be converted to decimal notation in the style
- \fR"[\-]\fIddd.ddd"\fR, where the number of digits after the radix
- character shall be equal to the precision specification. If the
- precision is missing, it shall be taken as 6; if the precision is
- explicitly zero and no
- .BR '#'
- flag is present, no radix character shall appear. If a radix character
- appears, at least one digit shall appear before it. The value shall be
- rounded in an implementation-defined manner to the appropriate number
- of digits.
- .RS 8
- .P
- A
- .BR double
- argument representing an infinity shall be converted in one of the
- styles
- .BR \(dq[-]inf\(dq
- or
- .BR \(dq[-]infinity\(dq ;
- which style is implementation-defined. A
- .BR double
- argument representing a NaN shall be converted in one of the styles
- .BR \(dq[-]nan\(dq
- or \fR"[\-]nan(\fIn-char-sequence\fR)"\fR; which style, and the
- meaning of any \fIn-char-sequence\fR, is implementation-defined. The
- .BR F
- conversion specifier produces
- .BR \(dqINF\(dq ,
- .BR \(dqINFINITY\(dq ,
- or
- .BR \(dqNAN\(dq
- instead of
- .BR \(dqinf\(dq ,
- .BR \(dqinfinity\(dq ,
- or
- .BR \(dqnan\(dq ,
- respectively.
- .RE
- .IP "\fRe\fR,\ \fRE\fR" 8
- The
- .BR double
- argument shall be converted in the style
- \fR"[\-]\fId.ddd\fRe\fR\(+-dd"\fR, where there shall be one digit
- before the radix character (which is non-zero if the argument is
- non-zero) and the number of digits after it shall be equal to the
- precision; if the precision is missing, it shall be taken as 6; if the
- precision is zero and no
- .BR '#'
- flag is present, no radix character shall appear. The value shall be
- rounded in an implementation-defined manner to the appropriate number
- of digits. The
- .BR E
- conversion wide character shall produce a number with
- .BR 'E'
- instead of
- .BR 'e'
- introducing the exponent. The exponent shall always contain at least
- two digits. If the value is zero, the exponent shall be zero.
- .RS 8
- .P
- A
- .BR double
- argument representing an infinity or NaN shall be converted in the
- style of an
- .BR f
- or
- .BR F
- conversion specifier.
- .RE
- .IP "\fRg\fR,\ \fRG\fR" 8
- The
- .BR double
- argument representing a floating-point number shall be converted in the
- style
- .BR f
- or
- .BR e
- (or in the style
- .BR F
- or
- .BR E
- in the case of a
- .BR G
- conversion specifier), depending on the value converted and the precision.
- Let
- .BR P
- equal the precision if non-zero, 6 if the precision is omitted, or 1 if the
- precision is zero. Then, if a conversion with style
- .BR E
- would have an exponent of
- .IR X :
- .RS 8
- .IP -- 4
- If
- .BR P >\c
- .IR X \(>=\-4,
- the conversion shall be with style
- .BR f
- (or
- .BR F )
- and precision
- .BR P \-(\c
- .IR X +1).
- .IP -- 4
- Otherwise, the conversion shall be with style
- .BR e
- (or
- .BR E )
- and precision
- .BR P \-1.
- .P
- Finally, unless the
- .BR '#'
- flag is used, any trailing zeros shall be removed from the fractional
- portion of the result and the decimal-point character shall be removed
- if there is no fractional portion remaining.
- .P
- A
- .BR double
- argument representing an infinity or NaN shall be converted in the
- style of an
- .BR f
- or
- .BR F
- conversion specifier.
- .RE
- .IP "\fRa\fR,\ \fRA\fR" 8
- A
- .BR double
- argument representing a floating-point number shall be converted in
- the style \fR"[\-]0x\fIh\fR.\fIhhhh\fRp\(+-\fId\fR"\fR, where there
- shall be one hexadecimal digit (which is non-zero if the argument is a
- normalized floating-point number and is otherwise unspecified) before
- the decimal-point wide character and the number of hexadecimal digits
- after it shall be equal to the precision; if the precision is missing
- and FLT_RADIX is a power of 2, then the precision shall be sufficient
- for an exact representation of the value; if the precision is missing
- and FLT_RADIX is not a power of 2, then the precision shall be sufficient
- to distinguish values of type
- .BR double ,
- except that trailing zeros may be omitted; if the precision is zero and
- the
- .BR '#'
- flag is not specified, no decimal-point wide character shall appear.
- The letters
- .BR \(dqabcdef\(dq
- are used for
- .BR a
- conversion and the letters
- .BR \(dqABCDEF\(dq
- for
- .BR A
- conversion. The
- .BR A
- conversion specifier produces a number with
- .BR 'X'
- and
- .BR 'P'
- instead of
- .BR 'x'
- and
- .BR 'p' .
- The exponent shall always contain 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 shall be zero.
- .RS 8
- .P
- A
- .BR double
- argument representing an infinity or NaN shall be converted in the
- style of an
- .BR f
- or
- .BR F
- conversion specifier.
- .RE
- .IP "\fRc\fP" 8
- If no
- .BR l
- (ell) qualifier is present, the
- .BR int
- argument shall be converted to a wide character as if by calling the
- \fIbtowc\fR()
- function and the resulting wide character shall be written. Otherwise,
- the
- .BR wint_t
- argument shall be converted to
- .BR wchar_t ,
- and written.
- .IP "\fRs\fP" 8
- If no
- .BR l
- (ell) qualifier is present, the application shall ensure that the
- argument is a pointer to a character array containing a character
- sequence beginning in the initial shift state. Characters from the
- array shall be converted as if by repeated calls to the
- \fImbrtowc\fR()
- function, with the conversion state described by an
- .BR mbstate_t
- object initialized to zero before the first character is converted, and
- written up to (but not including) the terminating null wide character.
- If the precision is specified, no more than that many wide characters
- shall be written. If the precision is not specified, or is greater than
- the size of the array, the application shall ensure that the array
- contains a null wide character.
- .RS 8
- .P
- If an
- .BR l
- (ell) qualifier is present, the application shall ensure that the
- argument is a pointer to an array of type
- .BR wchar_t .
- Wide characters from the array shall be 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 application
- shall ensure that the array contains a null wide character. If a
- precision is specified, no more than that many wide characters shall be
- written.
- .RE
- .IP "\fRp\fP" 8
- The application shall ensure that the argument is a pointer to
- .BR void .
- The value of the pointer shall be converted to a sequence of printable
- wide characters in an implementation-defined manner.
- .IP "\fRn\fP" 8
- The application shall ensure that the argument is 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
- \fIfwprintf\fR()
- functions. No argument shall be converted, but one shall be consumed.
- If the conversion specification includes any flags, a field width, or a
- precision, the behavior is undefined.
- .IP "\fRC\fP" 8
- Equivalent to
- .BR lc .
- .IP "\fRS\fP" 8
- Equivalent to
- .BR ls .
- .IP "\fR%\fR" 8
- Output a
- .BR '%'
- wide character; no argument shall be converted. The entire conversion
- specification shall be
- .BR %% .
- .P
- If a conversion specification does not match one of the above forms,
- the behavior is undefined.
- .P
- 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 shall be expanded to contain the conversion result.
- Characters generated by
- \fIfwprintf\fR()
- and
- \fIwprintf\fR()
- shall be printed as if
- \fIfputwc\fR()
- had been called.
- .P
- For
- .BR a
- and
- .BR A
- conversions, if FLT_RADIX is not a power of 2 and the result is not
- exactly representable in the given precision, the result should be one
- of the two adjacent numbers in hexadecimal floating style with the
- given precision, with the extra stipulation that the error should have
- a correct sign for the current rounding direction.
- .P
- For
- .BR e ,
- .BR E ,
- .BR f ,
- .BR F ,
- .BR g ,
- and
- .BR G
- conversion specifiers, if the number of significant decimal digits is
- at most DECIMAL_DIG, then the result should be correctly rounded. If
- the number of significant decimal digits is more than DECIMAL_DIG but
- the source value is exactly representable with DECIMAL_DIG digits, then
- the result should be an exact representation with trailing zeros.
- Otherwise, the source value is bounded by two adjacent decimal strings
- .IR L
- <
- .IR U ,
- both having DECIMAL_DIG significant digits; the value of the resultant
- decimal string
- .IR D
- should satisfy
- .IR L
- <=
- .IR D
- <=
- .IR U ,
- with the extra stipulation that the error should have a correct sign
- for the current rounding direction.
- .P
- The last data modification and last file status change timestamps
- of the file shall be marked for update between the call to a
- successful execution of
- \fIfwprintf\fR()
- or
- \fIwprintf\fR()
- and the next successful completion of a call to
- \fIfflush\fR()
- or
- \fIfclose\fR()
- on the same stream, or a call to
- \fIexit\fR()
- or
- \fIabort\fR().
- .SH "RETURN VALUE"
- Upon successful completion, these functions shall return the number of
- wide characters transmitted, excluding the terminating null wide character
- in the case of
- \fIswprintf\fR(),
- or a negative value if an output error was encountered,
- and set
- .IR errno
- to indicate the error.
- .P
- If
- .IR n
- or more wide characters were requested to be written,
- \fIswprintf\fR()
- shall return a negative value,
- and set
- .IR errno
- to indicate the error.
- .SH ERRORS
- For the conditions under which
- \fIfwprintf\fR()
- and
- \fIwprintf\fR()
- fail and may fail, refer to
- .IR "\fIfputwc\fR\^(\|)".
- .P
- In addition, all forms of
- \fIfwprintf\fR()
- shall fail if:
- .TP
- .BR EILSEQ
- A wide-character code that does not correspond to a valid character has
- been detected.
- .P
- In addition,
- \fIfwprintf\fR()
- and
- \fIwprintf\fR()
- may fail if:
- .TP
- .BR ENOMEM
- Insufficient storage space is available.
- .P
- The
- \fIswprintf\fR()
- shall fail if:
- .TP
- .BR EOVERFLOW
- The value of
- .IR n
- is greater than
- {INT_MAX}
- or the number of bytes needed to hold the output excluding the
- terminating null is greater than
- {INT_MAX}.
- .LP
- .IR "The following sections are informative."
- .SH "EXAMPLES"
- To print the language-independent date and time format, the following
- statement could be used:
- .sp
- .RS 4
- .nf
- wprintf(format, weekday, month, day, hour, min);
- .fi
- .P
- .RE
- .P
- For American usage,
- .IR format
- could be a pointer to the wide-character string:
- .sp
- .RS 4
- .nf
- L"%s, %s %d, %d:%.2d\en"
- .fi
- .P
- .RE
- .P
- producing the message:
- .sp
- .RS 4
- .nf
- Sunday, July 3, 10:02
- .fi
- .P
- .RE
- .P
- whereas for German usage,
- .IR format
- could be a pointer to the wide-character string:
- .sp
- .RS 4
- .nf
- L"%1$s, %3$d. %2$s, %4$d:%5$.2d\en"
- .fi
- .P
- .RE
- .P
- producing the message:
- .sp
- .RS 4
- .nf
- Sonntag, 3. Juli, 10:02
- .fi
- .P
- .RE
- .SH "APPLICATION USAGE"
- None.
- .SH RATIONALE
- If an implementation detects that there are insufficient
- arguments for the format, it is recommended that the function
- should fail and report an
- .BR [EINVAL]
- error.
- .SH "FUTURE DIRECTIONS"
- None.
- .SH "SEE ALSO"
- .IR "Section 2.5" ", " "Standard I/O Streams",
- .IR "\fIbtowc\fR\^(\|)",
- .IR "\fIfputwc\fR\^(\|)",
- .IR "\fIfwscanf\fR\^(\|)",
- .IR "\fImbrtowc\fR\^(\|)",
- .IR "\fIsetlocale\fR\^(\|)"
- .P
- The Base Definitions volume of POSIX.1\(hy2017,
- .IR "Chapter 7" ", " "Locale",
- .IR "\fB<inttypes.h>\fP",
- .IR "\fB<stdio.h>\fP",
- .IR "\fB<wchar.h>\fP"
- .\"
- .SH COPYRIGHT
- Portions of this text are reprinted and reproduced in electronic form
- from IEEE Std 1003.1-2017, Standard for Information Technology
- -- Portable Operating System Interface (POSIX), The Open Group Base
- Specifications Issue 7, 2018 Edition,
- Copyright (C) 2018 by the Institute of
- Electrical and Electronics Engineers, Inc and The Open Group.
- In the event of any discrepancy between this version and the original IEEE and
- The Open Group Standard, the original IEEE and The Open Group Standard
- is the referee document. The original Standard can be obtained online at
- http://www.opengroup.org/unix/online.html .
- .PP
- Any typographical or formatting errors that appear
- in this page are most likely
- to have been introduced during the conversion of the source files to
- man page format. To report such errors, see
- https://www.kernel.org/doc/man-pages/reporting_bugs.html .