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



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 performs
       formatted output of wide characters.

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

       The fwprintf and vfwprintf functions perform wide  charac-
       ter  output  to stream.  stream must not be byte oriented;
       see function fwide for more information.

       The swprintf and vswprintf functions perform wide  charac-
       ter output to an array of wide characters.  The programmer
       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  fol-
       lowing 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 dif-
       ferent:

       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) containing a
              multibyte character sequence beginning in the  ini-
              tial  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 charac-
              ters 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 termi-
              nating 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 char-
              acters 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(f),  fprintf(f),  snprintf(f), fputwc(c), fwide(e),
       wscanf(f)

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 cate-
       gory  of the current locale at run time is the same as the
       LC_CTYPE category of the current locale at  compile  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 univer-
       sal character names of the form \unnnn does not solve this
       problem.) Therefore, in  internationalized  programs,  the
       format  string  should  consist  of  ASCII wide characters
       only, or should be constructed at run time in an  interna-
       tionalized  way  (e.g. using gettext or iconv, followed by
       mbstowcs).



GNU                         1999-11-20                 WPRINTF(F)