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