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 \fIstdout\fP.
  76 \fIstdout\fP 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 \fIstream\fP.
  86 \fIstream\fP must not be byte oriented; see
  87 .BR fwide (3)
  88 for more information.
  89 .PP
  90 The
  91 .BR swprintf ()
  92 and
  93 .BR vswprintf ()
  94 functions
  95 perform wide-character output
  96 to an array of wide characters.
  97 The programmer must ensure that there is
  98 room for at least \fImaxlen\fP wide
  99 characters at \fIwcs\fP.
 100 .PP
 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 \fIformat\fP string is a wide-character string.
 114 .TP
 115 .B \(bu
 116 The output consists of wide characters, not bytes.
 117 .TP
 118 .B \(bu
 119 .BR swprintf ()
 120 and
 121 .BR vswprintf ()
 122 take a \fImaxlen\fP argument,
 123 .BR sprintf (3)
 124 and
 125 .BR vsprintf (3)
 126 do not.
 127 .RB ( snprintf (3)
 128 and
 129 .BR vsnprintf (3)
 130 take a \fImaxlen\fP argument, but these functions do not return \-1 upon
 131 buffer overflow on Linux.)
 132 .PP
 133 The treatment of the conversion characters \fBc\fP and \fBs\fP is different:
 134 .TP
 135 .B c
 136 If no
 137 .B l
 138 modifier is present, the
 139 .I int
 140 argument is converted to a wide character by a call to the
 141 .BR btowc (3)
 142 function, and the resulting wide character is written.
 143 If an
 144 .B l
 145 modifier is present, the
 146 .I wint_t
 147 (wide character) argument is written.
 148 .TP
 149 .B s
 150 If no
 151 .B l
 152 modifier is present: The
 153 .I "const\ char\ *"
 154 argument is expected to be a pointer to an array of character type
 155 (pointer to a string) containing a multibyte character sequence beginning
 156 in the initial shift state.
 157 Characters from the array are converted to
 158 wide characters (each by a call to the
 159 .BR mbrtowc (3)
 160 function with a conversion state starting in the initial state before
 161 the first byte).
 162 The resulting wide characters are written up to
 163 (but not including) the terminating null wide character.
 164 If a precision is
 165 specified, no more wide characters than the number specified are written.
 166 Note that the precision determines the number of
 167 .I wide characters
 168 written, not the number of
 169 .I bytes
 170 or
 171 .IR "screen positions" .
 172 The array must contain a terminating null byte, unless a precision is given
 173 and it is so small that the number of converted wide characters reaches it
 174 before the end of the array is reached.
 175 If an
 176 .B l
 177 modifier is present: The
 178 .I "const\ wchar_t\ *"
 179 argument is expected to be a pointer to an array of wide characters.
 180 Wide characters from the array are written up to (but not including) a
 181 terminating null wide character.
 182 If a precision is specified, no more than
 183 the number specified are written.
 184 The array must contain a terminating null
 185 wide character, unless a precision is given and it is smaller than or equal
 186 to the number of wide characters in the array.
 187 .SH RETURN VALUE
 188 The functions return the number of wide characters written, excluding the
 189 terminating null wide character in
 190 case of the functions
 191 .BR swprintf ()
 192 and
 193 .BR vswprintf ().
 194 They return \-1 when an error occurs.
 195 .SH CONFORMING TO
 196 C99.
 197 .SH NOTES
 198 The behavior of
 199 .BR wprintf ()
 200 et al. depends
 201 on the
 202 .B LC_CTYPE
 203 category of the
 204 current locale.
 205 .PP
 206 If the \fIformat\fP string contains non-ASCII wide characters, the program
 207 will work correctly only if the
 208 .B LC_CTYPE
 209 category of the current locale at
 210 run time is the same as the
 211 .B LC_CTYPE
 212 category of the current locale at
 213 compile time.
 214 This is because the
 215 .I wchar_t
 216 representation is platform- and locale-dependent.
 217 (The glibc represents
 218 wide characters using their Unicode (ISO-10646) code point, but other
 219 platforms don't do this.
 220 Also, the use of C99 universal character names
 221 of the form \\unnnn does not solve this problem.)
 222 Therefore, in
 223 internationalized programs, the \fIformat\fP string should consist of ASCII
 224 wide characters only, or should be constructed at run time in an
 225 internationalized way (e.g., using
 226 .BR gettext (3)
 227 or
 228 .BR iconv (3),
 229 followed by
 230 .BR mbstowcs (3)).
 231 .SH SEE ALSO
 232 .BR fprintf (3),
 233 .BR fputwc (3),
 234 .BR fwide (3),
 235 .BR printf (3),
 236 .BR snprintf (3)
 237 .\" .BR wscanf (3)