original/man3/wprintf.3

   1 .\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
   2 .\"
   3 .\" This is free documentation; you can redistribute it and/or
   4 .\" modify it under the terms of the GNU General Public License as
   5 .\" published by the Free Software Foundation; either version 2 of
   6 .\" the License, or (at your option) any later version.
   7 .\"
   8 .\" References consulted:
   9 .\"   GNU glibc-2 source code and manual
  10 .\"   Dinkumware C library reference http://www.dinkumware.com/
  11 .\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
  12 .\"   ISO/IEC 9899:1999
  13 .\"
  14 .TH WPRINTF 3  2011-09-17 "GNU" "Linux Programmer's Manual"
  15 .SH NAME
  16 wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted
  17 wide-character output conversion
  18 .SH SYNOPSIS
  19 .nf
  20 .B #include <stdio.h>
  21 .B #include <wchar.h>
  22 .sp
  23 .BI "int wprintf(const wchar_t *" format ", ...);"
  24 .BI "int fwprintf(FILE *" stream ", const wchar_t *" format ", ...);"
  25 .BI "int swprintf(wchar_t *" wcs ", size_t " maxlen ,
  26 .BI "             const wchar_t *" format ", ...);"
  27 .sp
  28 .BI "int vwprintf(const wchar_t *" format ", va_list " args );
  29 .BI "int vfwprintf(FILE *" stream ", const wchar_t *" format ", va_list " args );
  30 .BI "int vswprintf(wchar_t *" wcs ", size_t " maxlen ,
  31 .BI "              const wchar_t *" format ", va_list " args );
  32 .fi
  33 .sp
  34 .in -4n
  35 Feature Test Macro Requirements for glibc (see
  36 .BR feature_test_macros (7)):
  37 .in
  38 .sp
  39 .ad l
  40 All functions shown above:
  41 .RS 4
  42 .\" .BR wprintf (),
  43 .\" .BR fwprintf (),
  44 .\" .BR swprintf (),
  45 .\" .BR vwprintf (),
  46 .\" .BR vfwprintf (),
  47 .\" .BR vswprintf ():
  48 _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
  49 .br
  50 _ISOC95_SOURCE /* Since glibc 2.12 */ ||
  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 \fIstdout\fP.
  74 \fIstdout\fP must not be byte oriented; see
  75 .BR fwide (3)
  76 for more information.
  77 .PP
  78 The
  79 .BR fwprintf ()
  80 and
  81 .BR vfwprintf ()
  82 functions
  83 perform wide-character output to \fIstream\fP.
  84 \fIstream\fP must not be byte oriented; see
  85 .BR fwide (3)
  86 for more information.
  87 .PP
  88 The
  89 .BR swprintf ()
  90 and
  91 .BR vswprintf ()
  92 functions
  93 perform wide-character output
  94 to an array of wide characters.
  95 The programmer must ensure that there is
  96 room for at least \fImaxlen\fP wide
  97 characters at \fIwcs\fP.
  98 .PP
  99 These functions are like
 100 the
 101 .BR printf (3),
 102 .BR vprintf (3),
 103 .BR fprintf (3),
 104 .BR vfprintf (3),
 105 .BR sprintf (3),
 106 .BR vsprintf (3)
 107 functions except for the
 108 following differences:
 109 .TP
 110 .B \(bu
 111 The \fIformat\fP string is a wide-character string.
 112 .TP
 113 .B \(bu
 114 The output consists of wide characters, not bytes.
 115 .TP
 116 .B \(bu
 117 .BR swprintf ()
 118 and
 119 .BR vswprintf ()
 120 take a \fImaxlen\fP argument,
 121 .BR sprintf (3)
 122 and
 123 .BR vsprintf (3)
 124 do not.
 125 .RB ( snprintf (3)
 126 and
 127 .BR vsnprintf (3)
 128 take a \fImaxlen\fP argument, but these functions do not return \-1 upon
 129 buffer overflow on Linux.)
 130 .PP
 131 The treatment of the conversion characters \fBc\fP and \fBs\fP is different:
 132 .TP
 133 .B c
 134 If no
 135 .B l
 136 modifier is present, the
 137 .I int
 138 argument is converted to a wide character by a call to the
 139 .BR btowc (3)
 140 function, and the resulting wide character is written.
 141 If an
 142 .B l
 143 modifier is present, the
 144 .I wint_t
 145 (wide character) argument is written.
 146 .TP
 147 .B s
 148 If no
 149 .B l
 150 modifier is present: The
 151 .I "const\ char\ *"
 152 argument is expected to be a pointer to an array of character type
 153 (pointer to a string) containing a multibyte character sequence beginning
 154 in the initial shift state.
 155 Characters from the array are converted to
 156 wide characters (each by a call to the
 157 .BR mbrtowc (3)
 158 function with a conversion state starting in the initial state before
 159 the first byte).
 160 The resulting wide characters are written up to
 161 (but not including) the terminating null wide character.
 162 If a precision is
 163 specified, no more wide characters than the number specified are written.
 164 Note that the precision determines the number of
 165 .I wide characters
 166 written, not the number of
 167 .I bytes
 168 or
 169 .IR "screen positions" .
 170 The array must contain a terminating null byte, unless a precision is given
 171 and it is so small that the number of converted wide characters reaches it
 172 before the end of the array is reached.
 173 If an
 174 .B l
 175 modifier is present: The
 176 .I "const\ wchar_t\ *"
 177 argument is expected to be a pointer to an array of wide characters.
 178 Wide characters from the array are written up to (but not including) a
 179 terminating null wide character.
 180 If a precision is specified, no more than
 181 the number specified are written.
 182 The array must contain a terminating null
 183 wide character, unless a precision is given and it is smaller than or equal
 184 to the number of wide characters in the array.
 185 .SH "RETURN VALUE"
 186 The functions return the number of wide characters written, excluding the
 187 terminating null wide character in
 188 case of the functions
 189 .BR swprintf ()
 190 and
 191 .BR vswprintf ().
 192 They return \-1 when an error occurs.
 193 .SH "CONFORMING TO"
 194 C99.
 195 .SH NOTES
 196 The behavior of
 197 .BR wprintf ()
 198 et al. depends
 199 on the
 200 .B LC_CTYPE
 201 category of the
 202 current locale.
 203 .PP
 204 If the \fIformat\fP string contains non-ASCII wide characters, the program
 205 will only work correctly if the
 206 .B LC_CTYPE
 207 category of the current locale at
 208 run time is the same as the
 209 .B LC_CTYPE
 210 category of the current locale at
 211 compile time.
 212 This is because the
 213 .I wchar_t
 214 representation is platform- and locale-dependent.
 215 (The glibc represents
 216 wide characters using their Unicode (ISO-10646) code point, but other
 217 platforms don't do this.
 218 Also, the use of C99 universal character names
 219 of the form \\unnnn does not solve this problem.)
 220 Therefore, in
 221 internationalized programs, the \fIformat\fP string should consist of ASCII
 222 wide characters only, or should be constructed at run time in an
 223 internationalized way (e.g., using
 224 .BR gettext (3)
 225 or
 226 .BR iconv (3),
 227 followed by
 228 .BR mbstowcs (3)).
 229 .SH "SEE ALSO"
 230 .BR fprintf (3),
 231 .BR fputwc (3),
 232 .BR fwide (3),
 233 .BR printf (3),
 234 .BR snprintf (3)
 235 .\" .BR wscanf (3)