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