man3/wprintf.3

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