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