draft/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 .\" Japanese Version Copyright (c) 1999 HANATAKA Shinya
  15 .\"         all rights reserved.
  16 .\" Translated Tue Jan 11 00:55:36 JST 2000
  17 .\"         by HANATAKA Shinya <hanataka@abyss.rim.or.jp>
  18 .\"
  19 .TH WPRINTF 3  2011-09-17 "GNU" "Linux Programmer's Manual"
  20 .\"O .SH NAME
  21 .SH 名前
  22 .\"O wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted
  23 .\"O wide-character output conversion
  24 wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- ワイド文字を
  25 フォーマットして出力する
  26 .\"O .SH SYNOPSIS
  27 .SH 書式
  28 .nf
  29 .B #include <stdio.h>
  30 .B #include <wchar.h>
  31 .sp
  32 .BI "int wprintf(const wchar_t *" format ", ...);"
  33 .BI "int fwprintf(FILE *" stream ", const wchar_t *" format ", ...);"
  34 .BI "int swprintf(wchar_t *" wcs ", size_t " maxlen ,
  35 .BI "             const wchar_t *" format ", ...);"
  36 .sp
  37 .BI "int vwprintf(const wchar_t *" format ", va_list " args );
  38 .BI "int vfwprintf(FILE *" stream ", const wchar_t *" format ", va_list " args );
  39 .BI "int vswprintf(wchar_t *" wcs ", size_t " maxlen ,
  40 .BI "              const wchar_t *" format ", va_list " args );
  41 .fi
  42 .sp
  43 .in -4n
  44 .\"O Feature Test Macro Requirements for glibc (see
  45 .\"O .BR feature_test_macros (7)):
  46 glibc 向けの機能検査マクロの要件
  47 .RB ( feature_test_macros (7)
  48 参照):
  49 .in
  50 .sp
  51 .ad l
  52 .\"O All functions shown above:
  53 上記の全ての関数:
  54 .RS 4
  55 .\" .BR wprintf (),
  56 .\" .BR fwprintf (),
  57 .\" .BR swprintf (),
  58 .\" .BR vwprintf (),
  59 .\" .BR vfwprintf (),
  60 .\" .BR vswprintf ():
  61 _XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
  62 .br
  63 _ISOC95_SOURCE /* Since glibc 2.12 */ ||
  64 .br
  65 _POSIX_C_SOURCE\ >=\ 200112L;
  66 .br
  67 or
  68 .I cc\ -std=c99
  69 .RE
  70 .ad
  71 .\"O .SH DESCRIPTION
  72 .SH 説明
  73 .\"O The
  74 .\"O .BR wprintf ()
  75 .\"O family of functions is
  76 .\"O the wide-character equivalent of the
  77 .\"O .BR printf (3)
  78 .\"O family of functions.
  79 .\"O It performs formatted output of wide
  80 .\"O characters.
  81 .BR wprintf ()
  82 ファミリーの関数は
  83 .BR printf (3)
  84 ファミリーの関数の
  85 ワイド文字版である。これらはワイド文字をフォーマットして出力する。
  86 .PP
  87 .\"O The
  88 .\"O .BR wprintf ()
  89 .\"O and
  90 .\"O .BR vwprintf ()
  91 .\"O functions
  92 .\"O perform wide-character output to \fIstdout\fP.
  93 .\"O \fIstdout\fP must not be byte oriented; see
  94 .\"O .BR fwide (3)
  95 .\"O for more information.
  96 .BR wprintf ()
  97 と
  98 .BR vwprintf ()
  99 関数は \fIstdout\fP に出力を行なう。
 100 \fIstdout\fP がバイト単位入出力であってはいけない。より詳しい説明は
 101 .BR fwide (3)
 102 を参照すること。
 103 .PP
 104 .\"O The
 105 .\"O .BR fwprintf ()
 106 .\"O and
 107 .\"O .BR vfwprintf ()
 108 .\"O functions
 109 .\"O perform wide-character output to \fIstream\fP.
 110 .\"O \fIstream\fP must not be byte oriented; see
 111 .\"O .BR fwide (3)
 112 .\"O for more information.
 113 .BR fwprintf ()
 114 と
 115 .BR vfwprintf ()
 116 関数は \fIstream\fP にワイド文字出力
 117 を行なう。 \fIstream\fP がバイト単位入出力であってはいけない。
 118 より詳しい説明は
 119 .BR fwide (3)
 120 を参照すること。
 121 .PP
 122 .\"O The
 123 .\"O .BR swprintf ()
 124 .\"O and
 125 .\"O .BR vswprintf ()
 126 .\"O functions
 127 .\"O perform wide-character output
 128 .\"O to an array of wide characters.
 129 .\"O The programmer must ensure that there is
 130 .\"O room for at least \fImaxlen\fP wide
 131 .\"O characters at \fIwcs\fP.
 132 .BR swprintf ()
 133 と
 134 .BR vswprintf ()
 135 関数はワイド文字の配列に
 136 ワイド文字出力を行なう。プログラマーは \fIwcs\fP に最低でも
 137 \fImaxlen\fP 文字のワイド文字を出力できる空きがあることを保証しなければ
 138 ならない。
 139 .PP
 140 .\"O These functions are like
 141 .\"O the
 142 .\"O .BR printf (3),
 143 .\"O .BR vprintf (3),
 144 .\"O .BR fprintf (3),
 145 .\"O .BR vfprintf (3),
 146 .\"O .BR sprintf (3),
 147 .\"O .BR vsprintf (3)
 148 .\"O functions except for the
 149 .\"O following differences:
 150 これらの関数は
 151 .BR printf (3),
 152 .BR vprintf (3),
 153 .BR fprintf (3),
 154 .BR vfprintf (3),
 155 .BR sprintf (3),
 156 .BR vsprintf (3)
 157 関数に似ているが以下の
 158 点で異っている。
 159 .TP
 160 .B \(bu
 161 .\"O The \fIformat\fP string is a wide character string.
 162 \fIformat\fP がワイド文字列で与えられる。
 163 .TP
 164 .B \(bu
 165 .\"O The output consists of wide characters, not bytes.
 166 出力がバイトではなくワイド文字で構成される。
 167 .TP
 168 .B \(bu
 169 .\"O .BR swprintf ()
 170 .\"O and
 171 .\"O .BR vswprintf ()
 172 .\"O take a \fImaxlen\fP argument,
 173 .\"O .BR sprintf (3)
 174 .\"O and
 175 .\"O .BR vsprintf (3)
 176 .\"O do not.
 177 .\"O .RB ( snprintf (3)
 178 .\"O and
 179 .\"O .BR vsnprintf (3)
 180 .\"O take a \fImaxlen\fP argument, but these functions do not return \-1 upon
 181 .\"O buffer overflow on Linux.)
 182 .BR swprintf ()
 183 と
 184 .BR vswprintf ()
 185 は \fImaxlen\fP 引き数を取るが、
 186 .BR sprintf ()
 187 と
 188 .BR vsprintf ()
 189 は取らない
 190 .RB ( snprintf ()
 191 と
 192 .BR vsnprintf ()
 193 は \fImaxlen\fP 引き数を取るが
 194 これらの関数が Linux では、バッファーが溢れた場合でも \-1 を返さない)。
 195 .PP
 196 .\"O The treatment of the conversion characters \fBc\fP and \fBs\fP is different:
 197 \fBc\fP と \fBs\fP 変換文字の扱いが異っている:
 198 .TP
 199 .\"O .B c
 200 .\"O If no
 201 .\"O .B l
 202 .\"O modifier is present, the
 203 .\"O .I int
 204 .\"O argument is converted to a wide character by a call to the
 205 .\"O .BR btowc (3)
 206 .\"O function, and the resulting wide character is written.
 207 .\"O If an
 208 .\"O .B l
 209 .\"O modifier is present, the
 210 .\"O .I wint_t
 211 .\"O (wide character) argument is written.
 212 .B c
 213 もし
 214 .B l
 215 修飾子が存在しない場合は
 216 .I int
 217 引き数は
 218 .BR btowc (3)
 219 関数によってワイド文字に変換される。そして結果のワイド文字が出力される。
 220 .B l
 221 修飾子が存在する場合は
 222 .I wint_t
 223 (ワイド文字)引き数が出力される。
 224 .\"O .B s
 225 .\"O If no
 226 .\"O .B l
 227 .\"O modifier is present: The
 228 .\"O .I "const\ char\ *"
 229 .\"O argument is expected to be a pointer to an array of character type
 230 .\"O (pointer to a string) containing a multibyte character sequence beginning
 231 .\"O in the initial shift state.
 232 .\"O Characters from the array are converted to
 233 .\"O wide characters (each by a call to the
 234 .\"O .BR mbrtowc (3)
 235 .\"O function with a conversion state starting in the initial state before
 236 .\"O the first byte).
 237 .\"O The resulting wide characters are written up to
 238 .\"O (but not including) the terminating null wide character.
 239 .\"O If a precision is
 240 .\"O specified, no more wide characters than the number specified are written.
 241 .\"O Note that the precision determines the number of
 242 .\"O .I wide characters
 243 .\"O written, not the number of
 244 .\"O .I bytes
 245 .\"O or
 246 .\"O .IR "screen positions" .
 247 .TP
 248 .B s
 249 もし
 250 .B l
 251 修飾子が存在しない場合、
 252 .I "const\ char\ *"
 253 引き数は初期状態より始まるマルチバイト文字列を含んだ
 254 char 型の配列へのポインター(文字列へのポインター)とみなされる。
 255 配列の文字は(最初のバイト前に初期状態で変換を開始し、それぞれの文字を
 256 .BR mbrtowc (3)
 257 関数によって)ワイド文字へと変換される。結果のワイド文字は終端の
 258 ナルワイド文字の手前までが書き込まれる。精度(precision)が指定された
 259 場合、指定された数字を超えるワイド文字は書き込まれない。精度は
 260 書き込まれる
 261 .I バイト
 262 数や
 263 .I 画面上の位置
 264 ではなく
 265 .I ワイド文字
 266 の数を指定することに注意すること。
 267 .\"O The array must contain a terminating null byte, unless a precision is given
 268 .\"O and it is so small that the number of converted wide characters reaches it
 269 .\"O before the end of the array is reached.
 270 .\"O If an
 271 .\"O .B l
 272 .\"O modifier is present: The
 273 .\"O .I "const\ wchar_t\ *"
 274 .\"O argument is expected to be a pointer to an array of wide characters.
 275 .\"O Wide characters from the array are written up to (but not including) a
 276 .\"O terminating null wide character.
 277 .\"O If a precision is specified, no more than
 278 .\"O the number specified are written.
 279 .\"O The array must contain a terminating null
 280 .\"O wide character, unless a precision is given and it is smaller than or equal
 281 .\"O to the number of wide characters in the array.
 282 精度がない場合には配列の終端にナル文字を含む必要がある。
 283 精度を指定する場合には、配列の最後に到着する前に変換されたワイド文字の
 284 数がそれに到達するよう、精度は十分に小さな数でなければならない。
 285 もし
 286 .B l
 287 修飾子が存在する場合、
 288 .I "const\ wchar_t\ *"
 289 引き数はワイド文字の配列へのポインターとみなされる。
 290 配列のワイド文字列は終端のナルワイド文字の手間まで出力される。
 291 もし精度が指定された場合には指定された精度以上の文字は出力されない。
 292 精度を指定しない場合には終端のナルワイド文字を含む必要がある。
 293 精度を指定する場合にはそれはワイド文字の配列の大きさよりも小さくな
 294 ければならない。
 295 .\"O .SH "RETURN VALUE"
 296 .SH 返り値
 297 .\"O The functions return the number of wide characters written, excluding the
 298 .\"O terminating null wide character in
 299 .\"O case of the functions
 300 .\"O .BR swprintf ()
 301 .\"O and
 302 .\"O .BR vswprintf ().
 303 .\"O They return \-1 when an error occurs.
 304 これらの関数は書き込まれたワイド文字の文字数を返す。
 305 .BR swprintf ()
 306 と
 307 .BR vswprintf ()
 308 関数の場合は
 309 終端のナルワイド文字は含まない。エラーが起こった場合は \-1 を返す。
 310 .\"O .SH "CONFORMING TO"
 311 .SH 準拠
 312 C99.
 313 .\"O .SH NOTES
 314 .SH 注意
 315 .\"O The behavior of
 316 .\"O .BR wprintf ()
 317 .\"O et al. depends
 318 .\"O on the
 319 .\"O .B LC_CTYPE
 320 .\"O category of the
 321 .\"O current locale.
 322 .BR wprintf ()
 323 等の動作は現在のロケールの
 324 .B LC_CTYPE
 325 カテゴリに依存している。
 326 .PP
 327 .\"O If the \fIformat\fP string contains non-ASCII wide characters, the program
 328 .\"O will only work correctly if the
 329 .\"O .B LC_CTYPE
 330 .\"O category of the current locale at
 331 .\"O run time is the same as the
 332 .\"O .B LC_CTYPE
 333 .\"O category of the current locale at
 334 .\"O compile time.
 335 .\"O This is because the
 336 \fIformat\fP 文字列が ASCII 以外のワイド文字を含んでいる場合、
 337 実行時のロケールの
 338 .B LC_CTYPE
 339 カテゴリがコンパイル時の
 340 .B LC_CTYPE
 341 カテゴリと
 342 一致している場合にのみプログラムは正常に動作する。これは
 343 .I wchar_t
 344 .\"O representation is platform- and locale- dependent.
 345 .\"O (The glibc represents
 346 .\"O wide characters using their Unicode (ISO-10646) code point, but other
 347 .\"O platforms don't do this.
 348 .\"O Also, the use of ISO C99 universal character names
 349 .\"O of the form \\unnnn does not solve this problem.)
 350 の表現がロケールやプラットホームに依存していることに原因がある。
 351 (glibc ではワイド文字として Unicode (ISO-10646) のコードポイントを
 352 使用している。他のプラットホームではそうではない。同様に
 353 ISO C99 の \\unnnn 形式の汎用文字名称はこの問題を解決しない。)
 354 .\"O Therefore, in
 355 .\"O internationalized programs, the \fIformat\fP string should consist of ASCII
 356 .\"O wide characters only, or should be constructed at run time in an
 357 .\"O internationalized way (e.g., using
 358 .\"O .BR gettext (3)
 359 .\"O or
 360 .\"O .BR iconv (3),
 361 .\"O followed by
 362 .\"O .BR mbstowcs (3)).
 363 このため国際化されたプログラムでは \fIformat\fP 文字列を ASCII ワイド
 364 文字のみにするか、実行時に国際化された方法で構成する必要がある
 365 (例えば
 366 .BR gettext ()
 367 と
 368 .BR iconv ()
 369 や
 370 .BR mbstowcs ()
 371 を組み合わて使用する)。
 372 .\"O .SH "SEE ALSO"
 373 .SH 関連項目
 374 .BR fprintf (3),
 375 .BR fputwc (3),
 376 .BR fwide (3),
 377 .BR printf (3),
 378 .BR snprintf (3)
 379 .\" .BR wscanf (3)