ABCDEFGHIJKLMNOPQRSTUVWXYZ

swprintf

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



NAME
       wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf - 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 char-
       acters.

       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 character  output  to
       stream.  stream  must not be byte oriented; see function fwide for more
       information.

       The swprintf and vswprintf functions perform wide character  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 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  functions  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 result-
              ing 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 initial shift state. Characters from the array  are  con-
              verted  to  wide characters (each by a call to the mbrtowc func-
              tion with a conversion  state  starting  in  the  initial  state
              before  the first byte). The resulting wide characters are writ-
              ten up to (but not including) the terminating null wide  charac-
              ter.  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  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 characters from the array are
              written up to (but not including) a terminating null wide  char-
              acter.  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  written,  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 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 universal 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 internationalized  way
       (e.g. using gettext or iconv, followed by mbstowcs).



GNU                               1999-11-20                        WPRINTF(3)