vfwprintf(), vswprintf(), vwprintf() — Format and write wide characters of a STDARG argument list

Standards

Standards / Extensions	C or C++	Dependencies
ISO C Amendment C99 Single UNIX Specification, Version 3 Language Environment	both

Format

Non-XPG4:

#include <stdarg.h>
#include <wchar.h>

int vfwprintf(FILE * __restrict__ stream, 
              const wchar_t * __restrict__ format, va_list arg);
int vswprintf(wchar_t * __restrict__ wcs, size_t n, 
              const wchar_t * __restrict__ format, va_list arg);
int vwprintf(const wchar_t * __restrict__ format, va_list arg);

#define _OPEN_SYS_UNLOCKED_EXT 1
#include <wchar.h>

int vfwprintf_unlocked(FILE * __restrict__ stream, 
              const wchar_t * __restrict__ format, va_list arg);
int vwprintf_unlocked(const wchar_t * __restrict__ format, va_list arg);

XPG4:

#define _XOPEN_SOURCE
#define _MSE_PROTOS
#include <stdarg.h>
#include <wchar.h>

int vfwprintf(FILE * __restrict__ stream, 
              const wchar_t * __restrict__ format, va_list arg);
int vswprintf(wchar_t * __restrict__ wcs, size_t n, 
              const wchar_t * __restrict__ format, va_list arg);
int vwprintf(const wchar_t * __restrict__ format, va_list arg);

#define _OPEN_SYS_UNLOCKED_EXT 1
#include <wchar.h>

int vfwprintf_unlocked(FILE * __restrict__ stream, 
              const wchar_t * __restrict__ format, va_list arg);
int vwprintf_unlocked(const wchar_t * __restrict__ format, va_list arg);

General description

vfwprintf(), vswprintf(), and vwprintf() functions are equivalent to fprintf(), sprintf(), and printf() functions, respectively, except for the following:

Instead of being called with a variable number of arguments, they are called with an argument list as defined in stdarg.h.
For vswprintf(), the argument wcs specifies an array of type wchar_t, rather than an array of type char, into which the generated output is to be written.
The argument format specifies an array of type wchar_t, rather than an array of type char, which describes how subsequent arguments are converted for output.
%c without an l prefix means an integer argument is to be converted to wchar_t, as if by calling mbtowc(), 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 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 vswprintf(), 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.

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

vfwprintf_unlocked() and vwprintf_unlocked() are functionally equivalent to vfwprintf() and vwprintf() with the exception that they are not thread-safe. These functions may safely be used in a multithreaded application if and only if they are 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 vfwprintf(), vswprintf(), or vwprintf() 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.

Returned value

If successful, vfwprintf(), vswprintf(), and vwprintf() 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, vswprintf() returns a negative value and sets errno to indicate the error.

Note: In contrast to some UNIX-based implementations of the C language, the z/OS® XL C/C++ implementation of the vprintf() family increments the pointer to the variable arguments list. To control whether the pointer to the argument is incremented, call the va_end macro after each call to vfwprintf(), vswprintf(), or vwprintf().

Example

CELEBV06

⁄* CELEBV06 *⁄
#define _XOPEN_SOURCE
#define _MSE_PROTOS
#include <stdio.h>
#include <stdarg.h>
#include <wchar.h>

void vout(wchar_t *, size_t, wchar_t *, ...);

wchar_t *format3 = L"%S %d  %S";
wchar_t *format5 = L"%S  %d  %S  %d  %S";

int main(void)
{
   wchar_t wcstr[100];

   vout(wcstr, 100, format3, L"ONE", 2L, L"THREE");
   printf("%S\n",wcstr);
   vout(wcstr, 100, format5, L"ONE", 2L, L"THREE", 4L, L"FIVE");
   printf("%S\n",wcstr);
}

void vout(wchar_t *wcs, size_t n, wchar_t *fmt, ...)
{
   va_list arg_ptr;

   va_start(arg_ptr, fmt);
   if(vswprintf(wcs, n, fmt, arg_ptr)<0)
      perror("vswprintf() error");
   va_end(arg_ptr);
}