WPRINTF(3)         Linux Programmer's Manual         WPRINTF(3)





NAME
       wprintf,  fwprintf,  swprintf, vwprintf, vfwprintf, vsw-
       printf - formatted wide character output conversion

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

       int wprintf (const wchar_t* format, ...);
       int fwprintf (FILE* stream, const wchar_t* format, ...);
       int swprintf (wchar_t* wcs, size_t maxlen,
                     const wchar_t* format, ...);

       #include <stdarg.h>

       int vwprintf (const wchar_t* format, va_list args);
       int vfwprintf (FILE* stream, const wchar_t* format, va_list args);
       int vswprintf (wchar_t* wcs, size_t maxlen,
                      const wchar_t* format, va_list args);

DESCRIPTION
       The wprintf family of functions  is  the  wide-character
       equivalent  of  the  printf family of functions. It per-
       forms formatted output of wide characters.

       The wprintf and vwprintf functions perform wide  charac-
       ter  output to stdout. stdout must not be byte oriented;
       see function fwide for more information.

       The fwprintf and vfwprintf functions perform wide  char-
       acter  output  to  stream.  stream must not be byte ori-
       ented; see function fwide for more information.

       The swprintf and vswprintf functions perform wide  char-
       acter  output  to an array of wide characters.  The pro-
       grammer must ensure that there  is  room  for  at  least
       maxlen wide characters at wcs.

       These  functions  are like the printf, vprintf, fprintf,
       vfprintf, sprintf, vsprintf  functions  except  for  the
       following differences:

       o      The format string is a wide character string.

       o      The  output  consists  of  wide  characters,  not
              bytes.

       o      swprintf and vswprintf take  a  maxlen  argument,
              sprintf   and  vsprintf  do  not.  (snprintf  and
              vsnprintf take a maxlen argument, but these func-
              tions  do  not  return -1 upon buffer overflow on
              Linux.)

       The treatment of the conversion characters c  and  s  is
       different:

       c      If  no l modifier is present, the int argument is
              converted to a wide character by a  call  to  the
              btowc  function, and the resulting wide character
              is written.  If an l  modifier  is  present,  the
              wint_t (wide character) argument is written.

       s      If no l modifier is present: The ``const char *''
              argument is expected to be a pointer to an  array
              of  character type (pointer to a string) contain-
              ing a multibyte character sequence  beginning  in
              the  initial  shift  state.  Characters  from the
              array are converted to wide characters (each by a
              call  to  the  mbrtowc function with a conversion
              state starting in the initial  state  before  the
              first  byte).  The  resulting wide characters are
              written up to (but not including) the terminating
              null wide character. If a precision is specified,
              no more wide characters than the number specified
              are  written.  Note that the precision determines
              the number of wide characters  written,  not  the
              number  of  bytes or screen positions.  The array
              must contain a terminating null  byte,  unless  a
              precision  is  given  and it is so small that the
              number of converted wide  characters  reaches  it
              before  the end of the array is reached. -- If an
              l modifier is present: The  ``const  wchar_t  *''
              argument  is expected to be a pointer to an array
              of wide characters.   Wide  characters  from  the
              array  are  written  up  to (but not including) a
              terminating null wide character. If  a  precision
              is  specified,  no more than the number specified
              are written. The array must contain a terminating
              null  wide character, unless a precision is given
              and it is smaller than or equal to the number  of
              wide characters in the array.

RETURN VALUE
       The functions return the number of wide characters writ-
       ten, excluding the terminating null  wide  character  in
       case  of  the  functions  swprintf  and  vswprintf. They
       return -1 when an error occurs.

CONFORMING TO
       ISO/ANSI C, UNIX98

SEE ALSO
       printf(3), fprintf(3), snprintf(3), fputwc(3), fwide(3),
       wscanf(3)

NOTES
       The  behaviour of wprintf et al. depends on the LC_CTYPE
       category of the current locale.

       If the format string contains non-ASCII wide characters,
       the  program  will  only  work correctly if the LC_CTYPE
       category of the current locale at run time is  the  same
       as  the  LC_CTYPE category of the current locale at com-
       pile time. This is because the wchar_t representation is
       platform  and locale dependent. (The GNU libc represents
       wide characters using  their  Unicode  (ISO-10646)  code
       point,  but other platforms don't do this. Also, the use
       of ISO C99 universal character names of the form  \unnnn
       does not solve this problem.) Therefore, in internation-
       alized programs, the format  string  should  consist  of
       ASCII  wide characters only, or should be constructed at
       run time in an internationalized way (e.g. using gettext
       or iconv, followed by mbstowcs).



GNU                    November 20, 1999             WPRINTF(3)
