fwprintf(), swprintf(), wprintf() — Format and write wide characters

Standards

Standards / Extensions C or C++ Dependencies

ISO C Amendment
C99
Single UNIX Specification, Version 3
Language Environment

 both  

Format

Non-XPG4: 
#include <wchar.h>

int fwprintf(FILE * __restrict__ stream, const wchar_t * __restrict__ format, …);
int swprintf(wchar_t * __restrict__ wcs, size_t n, const wchar_t * __restrict__ format, …);
int wprintf(const wchar_t * __restrict__ format, …);

#define _OPEN_SYS_UNLOCKED_EXT 1
#include <wchar.h>

int fwprintf_unlocked(FILE * __restrict__ stream, const wchar_t * __restrict__ format, …);
int wprintf_unlocked(const wchar_t * __restrict__ format, …);
XPG4: 
#define _XOPEN_SOURCE
#define _MSE_PROTOS
#include <wchar.h>

int fwprintf(FILE * __restrict__ stream, const wchar_t * __restrict__ format, …);
int swprintf(wchar_t *__restrict__ wcs, size_t n, const wchar_t * __restrict__ format, …);
int wprintf(const wchar_t * __restrict__ format, …);

#define _OPEN_SYS_UNLOCKED_EXT 1
#include <wchar.h>

int fwprintf_unlocked(FILE * __restrict__ stream, const wchar_t * __restrict__ format, …);
int wprintf_unlocked(const wchar_t * __restrict__ format, …);

General description

The fwprintf(), swprintf() and wprintf() functions are equivalent to fprintf(), sprintf() and printf(), respectively, except for the following:
  • For swprintf(), the argument wcs specifies an array of type wchar_t into which the generated output is to be written, rather than an array of type char.
  • The argument format specifies an array of type wchar_t that describes how subsequent arguments are converted for output, rather than an array of type char.
  • %c without an l prefix means an int arg is to be converted to wchar_t, as if mbtowc() were called, and then written.
  • %c with l prefix means a wint_t is converted to wchar_t and then written.
  • %s without an l prefix means a character array containing a multibyte character sequence is to be converted to an array of wchar_t and then written. The conversion will take place as if mbrtowc() were called repeatedly.
  • %s with l prefix means an array of wchar_t will be written. The array is written up to but not including the terminating NULL character, unless the precision specifies a shorter output.

For swprintf(), a NULL wide character is written at the end of the wide characters written; the NULL wide character is not counted as part of the returned sum. If copying takes place between objects that overlap, the behavior is undefined.

fwprintf_unlocked() family is functionally equivalent to fwprintf() family with the exception that it is not thread-safe. This function can safely be used in a multithreaded application if and only if it is called while the invoking thread owns the (FILE*) object, as is the case after a successful call to either the flockfile() or ftrylockfile() function.

Special behavior for XPG4: If you define any feature test macro specifying XPG4 behavior before the statement in your program source file to include the wchar header, then you must also define the _MSE_PROTOS feature test macro to make the declaration of the fwprintf(), swprintf() or wprintf() function in the wchar header available when you compile your program. Please see Table 1 for a list of XPG4 and other feature test macros.

Note: The fwprintf() and wprintf() functions have a dependency on the level of the Enhanced ASCII Extensions. See Enhanced ASCII support for details.

Returned value

If successful, fwprintf(), wprintf(), and swprintf() return the number of wide characters written, not counting the terminating NULL wide character.

If unsuccessful, a negative value is returned.

If n or more wide characters were requested to be written, swprintf() returns a negative value and sets errno to indicate the error.

Related information

Parent topic: Library functions