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