man3/wprintf.3

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