1WPRINTF(3)                 Linux Programmer's Manual                WPRINTF(3)
2
3
4

NAME

6       wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf - formatted
7       wide-character output conversion
8

SYNOPSIS

10       #include <stdio.h>
11       #include <wchar.h>
12
13       int wprintf(const wchar_t *format, ...);
14       int fwprintf(FILE *stream, const wchar_t *format, ...);
15       int swprintf(wchar_t *wcs, size_t maxlen,
16                    const wchar_t *format, ...);
17
18       int vwprintf(const wchar_t *format, va_list args);
19       int vfwprintf(FILE *stream, const wchar_t *format, va_list args);
20       int vswprintf(wchar_t *wcs, size_t maxlen,
21                     const wchar_t *format, va_list args);
22
23   Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
24
25       All functions shown above: _XOPEN_SOURCE >= 500 || _ISOC99_SOURCE; or
26       cc -std=c99
27

DESCRIPTION

29       The  wprintf()  family of functions is the wide-character equivalent of
30       the printf(3) family of functions.  It  performs  formatted  output  of
31       wide characters.
32
33       The wprintf() and vwprintf() functions perform wide-character output to
34       stdout.  stdout must not be byte oriented; see fwide(3) for more infor‐
35       mation.
36
37       The  fwprintf() and vfwprintf() functions perform wide-character output
38       to stream.  stream must not be byte oriented;  see  fwide(3)  for  more
39       information.
40
41       The  swprintf() and vswprintf() functions perform wide-character output
42       to an array of wide characters.  The programmer must ensure that  there
43       is room for at least maxlen wide characters at wcs.
44
45       These   functions  are  like  the  printf(3),  vprintf(3),  fprintf(3),
46       vfprintf(3), sprintf(3), vsprintf(3) functions except for the following
47       differences:
48
49       ·      The format string is a wide-character string.
50
51       ·      The output consists of wide characters, not bytes.
52
53       ·      swprintf()  and  vswprintf()  take a maxlen argument, sprintf(3)
54              and vsprintf(3) do not.  (snprintf(3) and  vsnprintf(3)  take  a
55              maxlen  argument, but these functions do not return -1 upon buf‐
56              fer overflow on Linux.)
57
58       The treatment of the conversion characters c and s is different:
59
60       c      If no l modifier is present, the int argument is converted to  a
61              wide  character  by  a  call  to  the btowc(3) function, and the
62              resulting wide character  is  written.   If  an  l  modifier  is
63              present, the wint_t (wide character) argument is written.
64
65       s      If  no  l  modifier  is  present:  The  const char * argument is
66              expected to be a pointer to an array of character type  (pointer
67              to a string) containing a multibyte character sequence beginning
68              in the initial shift state.  Characters from the array are  con‐
69              verted  to  wide  characters  (each  by a call to the mbrtowc(3)
70              function with a conversion state starting in the  initial  state
71              before the first byte).  The resulting wide characters are writ‐
72              ten up to (but not including) the terminating null wide  charac‐
73              ter.   If a precision is specified, no more wide characters than
74              the number specified  are  written.   Note  that  the  precision
75              determines the number of wide characters written, not the number
76              of bytes or screen positions.  The array must contain  a  termi‐
77              nating null byte, unless a precision is given and it is so small
78              that the number of converted wide characters reaches  it  before
79              the  end  of the array is reached.  If an l modifier is present:
80              The const wchar_t * argument is expected to be a pointer  to  an
81              array  of  wide  characters.  Wide characters from the array are
82              written up to (but not including) a terminating null wide  char‐
83              acter.   If  a  precision  is specified, no more than the number
84              specified are written.  The array  must  contain  a  terminating
85              null  wide  character,  unless  a  precision  is given and it is
86              smaller than or equal to the number of wide  characters  in  the
87              array.
88

RETURN VALUE

90       The  functions  return the number of wide characters written, excluding
91       the terminating null wide character in case of the functions swprintf()
92       and vswprintf().  They return -1 when an error occurs.
93

CONFORMING TO

95       C99.
96

NOTES

98       The  behavior  of  wprintf() et al. depends on the LC_CTYPE category of
99       the current locale.
100
101       If the format string contains non-ASCII wide  characters,  the  program
102       will only work correctly if the LC_CTYPE category of the current locale
103       at run time is the same as the LC_CTYPE category of the current  locale
104       at  compile  time.  This is because the wchar_t representation is plat‐
105       form- and locale-dependent.   (The  glibc  represents  wide  characters
106       using  their  Unicode (ISO-10646) code point, but other platforms don't
107       do this.  Also, the use of C99 universal character names  of  the  form
108       \unnnn  does  not solve this problem.)  Therefore, in internationalized
109       programs, the format string should consist  of  ASCII  wide  characters
110       only,  or should be constructed at run time in an internationalized way
111       (e.g., using gettext(3) or iconv(3), followed by mbstowcs(3)).
112

SEE ALSO

114       fprintf(3), fputwc(3), fwide(3), printf(3), snprintf(3)
115

COLOPHON

117       This page is part of release 3.25 of the Linux  man-pages  project.   A
118       description  of  the project, and information about reporting bugs, can
119       be found at http://www.kernel.org/doc/man-pages/.
120
121
122
123GNU                               2007-07-26                        WPRINTF(3)
Impressum