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