man3/wprintf.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_ONEPARA)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\" %%%LICENSE_END
   9 .\"
  10 .\" References consulted:
  11 .\"   GNU glibc-2 source code and manual
  12 .\"   Dinkumware C library reference http://www.dinkumware.com/
  13 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  14 .\"   ISO/IEC 9899:1999
  15 .\"
  16 .TH WPRINTF 3  2019-03-06 "GNU" "Linux Programmer's Manual"
  17 .SH NAME
  18 wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted
  19 wide-character output conversion
  20 .SH SYNOPSIS
  21 .nf
  22 .B #include <stdio.h>
  23 .B #include <wchar.h>
  24 .PP
  25 .BI "int wprintf(const wchar_t *" format ", ...);"
  26 .BI "int fwprintf(FILE *" stream ", const wchar_t *" format ", ...);"
  27 .BI "int swprintf(wchar_t *" wcs ", size_t " maxlen ,
  28 .BI "             const wchar_t *" format ", ...);"
  29 .PP
  30 .BI "int vwprintf(const wchar_t *" format ", va_list " args );
  31 .BI "int vfwprintf(FILE *" stream ", const wchar_t *" format ", va_list " args );
  32 .BI "int vswprintf(wchar_t *" wcs ", size_t " maxlen ,
  33 .BI "              const wchar_t *" format ", va_list " args );
  34 .fi
  35 .PP
  36 .in -4n
  37 Feature Test Macro Requirements for glibc (see
  38 .BR feature_test_macros (7)):
  39 .in
  40 .PP
  41 .ad l
  42 All functions shown above:
  43 .RS 4
  44 .\" .BR wprintf (),
  45 .\" .BR fwprintf (),
  46 .\" .BR swprintf (),
  47 .\" .BR vwprintf (),
  48 .\" .BR vfwprintf (),
  49 .\" .BR vswprintf ():
  50 _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
  51 .br
  52 _POSIX_C_SOURCE\ >=\ 200112L
  53 .RE
  54 .ad
  55 .SH DESCRIPTION
  56 The
  57 .BR wprintf ()
  58 family of functions is
  59 the wide-character equivalent of the
  60 .BR printf (3)
  61 family of functions.
  62 It performs formatted output of wide
  63 characters.
  64 .PP
  65 The
  66 .BR wprintf ()
  67 and
  68 .BR vwprintf ()
  69 functions
  70 perform wide-character output to
  71 .IR stdout .
  72 .I stdout
  73 must not be byte oriented; see
  74 .BR fwide (3)
  75 for more information.
  76 .PP
  77 The
  78 .BR fwprintf ()
  79 and
  80 .BR vfwprintf ()
  81 functions
  82 perform wide-character output to
  83 .IR stream .
  84 .I stream
  85 must not be byte oriented; see
  86 .BR fwide (3)
  87 for more information.
  88 .PP
  89 The
  90 .BR swprintf ()
  91 and
  92 .BR vswprintf ()
  93 functions
  94 perform wide-character output
  95 to an array of wide characters.
  96 The programmer must ensure that there is
  97 room for at least
  98 .I maxlen
  99 wide
 100 characters at
 101 .IR wcs .
 102 .PP
 103 These functions are like
 104 the
 105 .BR printf (3),
 106 .BR vprintf (3),
 107 .BR fprintf (3),
 108 .BR vfprintf (3),
 109 .BR sprintf (3),
 110 .BR vsprintf (3)
 111 functions except for the
 112 following differences:
 113 .TP
 114 .B \(bu
 115 The
 116 .I format
 117 string is a wide-character string.
 118 .TP
 119 .B \(bu
 120 The output consists of wide characters, not bytes.
 121 .TP
 122 .B \(bu
 123 .BR swprintf ()
 124 and
 125 .BR vswprintf ()
 126 take a
 127 .I maxlen
 128 argument,
 129 .BR sprintf (3)
 130 and
 131 .BR vsprintf (3)
 132 do not.
 133 .RB ( snprintf (3)
 134 and
 135 .BR vsnprintf (3)
 136 take a
 137 .I maxlen
 138 argument, but these functions do not return \-1 upon
 139 buffer overflow on Linux.)
 140 .PP
 141 The treatment of the conversion characters
 142 .BR c
 143 and
 144 .B s
 145 is different:
 146 .TP
 147 .B c
 148 If no
 149 .B l
 150 modifier is present, the
 151 .I int
 152 argument is converted to a wide character by a call to the
 153 .BR btowc (3)
 154 function, and the resulting wide character is written.
 155 If an
 156 .B l
 157 modifier is present, the
 158 .I wint_t
 159 (wide character) argument is written.
 160 .TP
 161 .B s
 162 If no
 163 .B l
 164 modifier is present: the
 165 .I "const\ char\ *"
 166 argument is expected to be a pointer to an array of character type
 167 (pointer to a string) containing a multibyte character sequence beginning
 168 in the initial shift state.
 169 Characters from the array are converted to
 170 wide characters (each by a call to the
 171 .BR mbrtowc (3)
 172 function with a conversion state starting in the initial state before
 173 the first byte).
 174 The resulting wide characters are written up to
 175 (but not including) the terminating null wide character (L\(aq\e0\(aq).
 176 If a precision is
 177 specified, no more wide characters than the number specified are written.
 178 Note that the precision determines the number of
 179 .I wide characters
 180 written, not the number of
 181 .I bytes
 182 or
 183 .IR "screen positions" .
 184 The array must contain a terminating null byte (\(aq\e0\(aq),
 185 unless a precision is given
 186 and it is so small that the number of converted wide characters reaches it
 187 before the end of the array is reached.
 188 If an
 189 .B l
 190 modifier is present: the
 191 .I "const\ wchar_t\ *"
 192 argument is expected to be a pointer to an array of wide characters.
 193 Wide characters from the array are written up to (but not including) a
 194 terminating null wide character.
 195 If a precision is specified, no more than
 196 the number specified are written.
 197 The array must contain a terminating null
 198 wide character, unless a precision is given and it is smaller than or equal
 199 to the number of wide characters in the array.
 200 .SH RETURN VALUE
 201 The functions return the number of wide characters written, excluding the
 202 terminating null wide character in
 203 case of the functions
 204 .BR swprintf ()
 205 and
 206 .BR vswprintf ().
 207 They return \-1 when an error occurs.
 208 .SH ATTRIBUTES
 209 For an explanation of the terms used in this section, see
 210 .BR attributes (7).
 211 .TS
 212 allbox;
 213 lbw24 lb lb
 214 l l l.
 215 Interface       Attribute       Value
 216 T{
 217 .BR wprintf (),
 218 .BR fwprintf (),
 219 .br
 220 .BR swprintf (),
 221 .BR vwprintf (),
 222 .br
 223 .BR vfwprintf (),
 224 .BR vswprintf ()
 225 T}      Thread safety   MT-Safe locale
 226 .TE
 227 .sp 1
 228 .SH CONFORMING TO
 229 POSIX.1-2001, POSIX.1-2008, C99.
 230 .SH NOTES
 231 The behavior of
 232 .BR wprintf ()
 233 et al. depends
 234 on the
 235 .B LC_CTYPE
 236 category of the
 237 current locale.
 238 .PP
 239 If the
 240 .I format
 241 string contains non-ASCII wide characters, the program
 242 will work correctly only if the
 243 .B LC_CTYPE
 244 category of the current locale at
 245 run time is the same as the
 246 .B LC_CTYPE
 247 category of the current locale at
 248 compile time.
 249 This is because the
 250 .I wchar_t
 251 representation is platform- and locale-dependent.
 252 (The glibc represents
 253 wide characters using their Unicode (ISO-10646) code point, but other
 254 platforms don't do this.
 255 Also, the use of C99 universal character names
 256 of the form \eunnnn does not solve this problem.)
 257 Therefore, in
 258 internationalized programs, the
 259 .I format
 260 string should consist of ASCII
 261 wide characters only, or should be constructed at run time in an
 262 internationalized way (e.g., using
 263 .BR gettext (3)
 264 or
 265 .BR iconv (3),
 266 followed by
 267 .BR mbstowcs (3)).
 268 .SH SEE ALSO
 269 .BR fprintf (3),
 270 .BR fputwc (3),
 271 .BR fwide (3),
 272 .BR printf (3),
 273 .BR snprintf (3)
 274 .\" .BR wscanf (3)