.\" Copyright (c) Bruno Haible <haible@clisp.cons.org>
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" References consulted:
.\"   GNU glibc-2 source code and manual
.\"   Dinkumware C library reference http://www.dinkumware.com/
.\"   OpenGroup's Single UNIX specification http://www.UNIX-systems.org/online.html
.\"   ISO/IEC 9899:1999
.\"
.\" Japanese Version Copyright (c) 1999 HANATAKA Shinya
.\"         all rights reserved.
.\" Translated Tue Jan 11 00:55:36 JST 2000
.\"         by HANATAKA Shinya <hanataka@abyss.rim.or.jp>
.\"
.TH WPRINTF 3  2010-09-20 "GNU" "Linux Programmer's Manual"
.\"O .SH NAME
.SH 名前
.\"O wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- formatted
.\"O wide-character output conversion
wprintf, fwprintf, swprintf, vwprintf, vfwprintf, vswprintf \- ワイド文字を
フォーマットして出力する
.\"O .SH SYNOPSIS
.SH 書式
.nf
.B #include <stdio.h>
.B #include <wchar.h>
.sp
.BI "int wprintf(const wchar_t *" format ", ...);"
.BI "int fwprintf(FILE *" stream ", const wchar_t *" format ", ...);"
.BI "int swprintf(wchar_t *" wcs ", size_t " maxlen ,
.BI "             const wchar_t *" format ", ...);"
.sp
.BI "int vwprintf(const wchar_t *" format ", va_list " args );
.BI "int vfwprintf(FILE *" stream ", const wchar_t *" format ", va_list " args );
.BI "int vswprintf(wchar_t *" wcs ", size_t " maxlen ,
.BI "              const wchar_t *" format ", va_list " args );
.fi
.sp
.in -4n
.\"O Feature Test Macro Requirements for glibc (see
.\"O .BR feature_test_macros (7)):
glibc 向けの機能検査マクロの要件
.RB ( feature_test_macros (7)
参照):
.in
.sp
.ad l
.\"O All functions shown above:
上記の全ての関数:
.RS 4
.\" .BR wprintf (),
.\" .BR fwprintf (),
.\" .BR swprintf (),
.\" .BR vwprintf (),
.\" .BR vfwprintf (),
.\" .BR vswprintf ():
_XOPEN_SOURCE\ >=\ 500 || _ISOC99_SOURCE ||
_POSIX_C_SOURCE\ >=\ 200112L;
.br
or
.I cc\ -std=c99
.RE
.ad
.\"O .SH DESCRIPTION
.SH 説明
.\"O The
.\"O .BR wprintf ()
.\"O family of functions is
.\"O the wide-character equivalent of the
.\"O .BR printf (3)
.\"O family of functions.
.\"O It performs formatted output of wide
.\"O characters.
.BR wprintf ()
ファミリーの関数は
.BR printf (3)
ファミリーの関数の
ワイド文字版である。これらはワイド文字をフォーマットして出力する。
.PP
.\"O The
.\"O .BR wprintf ()
.\"O and
.\"O .BR vwprintf ()
.\"O functions
.\"O perform wide-character output to \fIstdout\fP.
.\"O \fIstdout\fP must not be byte oriented; see
.\"O .BR fwide (3)
.\"O for more information.
.BR wprintf ()
と
.BR vwprintf ()
関数は \fIstdout\fP に出力を行なう。
\fIstdout\fP がバイト単位入出力であってはいけない。より詳しい説明は
.BR fwide (3)
を参照すること。
.PP
.\"O The
.\"O .BR fwprintf ()
.\"O and
.\"O .BR vfwprintf ()
.\"O functions
.\"O perform wide-character output to \fIstream\fP.
.\"O \fIstream\fP must not be byte oriented; see
.\"O .BR fwide (3)
.\"O for more information.
.BR fwprintf ()
と
.BR vfwprintf ()
関数は \fIstream\fP にワイド文字出力
を行なう。 \fIstream\fP がバイト単位入出力であってはいけない。
より詳しい説明は
.BR fwide (3)
を参照すること。
.PP
.\"O The
.\"O .BR swprintf ()
.\"O and
.\"O .BR vswprintf ()
.\"O functions
.\"O perform wide-character output
.\"O to an array of wide characters.
.\"O The programmer must ensure that there is
.\"O room for at least \fImaxlen\fP wide
.\"O characters at \fIwcs\fP.
.BR swprintf ()
と
.BR vswprintf ()
関数はワイド文字の配列に
ワイド文字出力を行なう。プログラマーは \fIwcs\fP に最低でも
\fImaxlen\fP 文字のワイド文字を出力できる空きがあることを保証しなければ
ならない。
.PP
.\"O These functions are like
.\"O the
.\"O .BR printf (3),
.\"O .BR vprintf (3),
.\"O .BR fprintf (3),
.\"O .BR vfprintf (3),
.\"O .BR sprintf (3),
.\"O .BR vsprintf (3)
.\"O functions except for the
.\"O following differences:
これらの関数は
.BR printf (3),
.BR vprintf (3),
.BR fprintf (3),
.BR vfprintf (3),
.BR sprintf (3),
.BR vsprintf (3)
関数に似ているが以下の
点で異っている。
.TP
.B \(bu
.\"O The \fIformat\fP string is a wide character string.
\fIformat\fP がワイド文字列で与えられる。
.TP
.B \(bu
.\"O The output consists of wide characters, not bytes.
出力がバイトではなくワイド文字で構成される。
.TP
.B \(bu
.\"O .BR swprintf ()
.\"O and
.\"O .BR vswprintf ()
.\"O take a \fImaxlen\fP argument,
.\"O .BR sprintf (3)
.\"O and
.\"O .BR vsprintf (3)
.\"O do not.
.\"O .RB ( snprintf (3)
.\"O and
.\"O .BR vsnprintf (3)
.\"O take a \fImaxlen\fP argument, but these functions do not return \-1 upon
.\"O buffer overflow on Linux.)
.BR swprintf ()
と
.BR vswprintf ()
は \fImaxlen\fP 引き数を取るが、
.BR sprintf ()
と
.BR vsprintf ()
は取らない
.RB ( snprintf ()
と
.BR vsnprintf ()
は \fImaxlen\fP 引き数を取るが
これらの関数が Linux では、バッファーが溢れた場合でも \-1 を返さない)。
.PP
.\"O The treatment of the conversion characters \fBc\fP and \fBs\fP is different:
\fBc\fP と \fBs\fP 変換文字の扱いが異っている:
.TP
.\"O .B c
.\"O If no
.\"O .B l
.\"O modifier is present, the
.\"O .I int
.\"O argument is converted to a wide character by a call to the
.\"O .BR btowc (3)
.\"O function, and the resulting wide character is written.
.\"O If an
.\"O .B l
.\"O modifier is present, the
.\"O .I wint_t
.\"O (wide character) argument is written.
.B c
もし
.B l
修飾子が存在しない場合は
.I int
引き数は
.BR btowc (3)
関数によってワイド文字に変換される。そして結果のワイド文字が出力される。
.B l
修飾子が存在する場合は
.I wint_t
(ワイド文字)引き数が出力される。
.\"O .B s
.\"O If no
.\"O .B l
.\"O modifier is present: The
.\"O .I "const\ char\ *"
.\"O argument is expected to be a pointer to an array of character type
.\"O (pointer to a string) containing a multibyte character sequence beginning
.\"O in the initial shift state.
.\"O Characters from the array are converted to
.\"O wide characters (each by a call to the
.\"O .BR mbrtowc (3)
.\"O function with a conversion state starting in the initial state before
.\"O the first byte).
.\"O The resulting wide characters are written up to
.\"O (but not including) the terminating null wide character.
.\"O If a precision is
.\"O specified, no more wide characters than the number specified are written.
.\"O Note that the precision determines the number of
.\"O .I wide characters
.\"O written, not the number of
.\"O .I bytes
.\"O or
.\"O .IR "screen positions" .
.TP
.B s
もし
.B l
修飾子が存在しない場合、
.I "const\ char\ *"
引き数は初期状態より始まるマルチバイト文字列を含んだ
char 型の配列へのポインター(文字列へのポインター)とみなされる。
配列の文字は(最初のバイト前に初期状態で変換を開始し、それぞれの文字を
.BR mbrtowc (3)
関数によって)ワイド文字へと変換される。結果のワイド文字は終端の
ナルワイド文字の手前までが書き込まれる。精度(precision)が指定された
場合、指定された数字を超えるワイド文字は書き込まれない。精度は
書き込まれる
.I バイト
数や
.I 画面上の位置
ではなく
.I ワイド文字
の数を指定することに注意すること。
.\"O The array must contain a terminating null byte, unless a precision is given
.\"O and it is so small that the number of converted wide characters reaches it
.\"O before the end of the array is reached.
.\"O If an
.\"O .B l
.\"O modifier is present: The
.\"O .I "const\ wchar_t\ *"
.\"O argument is expected to be a pointer to an array of wide characters.
.\"O Wide characters from the array are written up to (but not including) a
.\"O terminating null wide character.
.\"O If a precision is specified, no more than
.\"O the number specified are written.
.\"O The array must contain a terminating null
.\"O wide character, unless a precision is given and it is smaller than or equal
.\"O to the number of wide characters in the array.
精度がない場合には配列の終端にナル文字を含む必要がある。
精度を指定する場合には、配列の最後に到着する前に変換されたワイド文字の
数がそれに到達するよう、精度は十分に小さな数でなければならない。
もし
.B l
修飾子が存在する場合、
.I "const\ wchar_t\ *"
引き数はワイド文字の配列へのポインターとみなされる。
配列のワイド文字列は終端のナルワイド文字の手間まで出力される。
もし精度が指定された場合には指定された精度以上の文字は出力されない。
精度を指定しない場合には終端のナルワイド文字を含む必要がある。
精度を指定する場合にはそれはワイド文字の配列の大きさよりも小さくな
ければならない。
.\"O .SH "RETURN VALUE"
.SH 返り値
.\"O The functions return the number of wide characters written, excluding the
.\"O terminating null wide character in
.\"O case of the functions
.\"O .BR swprintf ()
.\"O and
.\"O .BR vswprintf ().
.\"O They return \-1 when an error occurs.
これらの関数は書き込まれたワイド文字の文字数を返す。
.BR swprintf ()
と
.BR vswprintf ()
関数の場合は
終端のナルワイド文字は含まない。エラーが起こった場合は \-1 を返す。
.\"O .SH "CONFORMING TO"
.SH 準拠
C99.
.\"O .SH NOTES
.SH 注意
.\"O The behavior of
.\"O .BR wprintf ()
.\"O et al. depends
.\"O on the
.\"O .B LC_CTYPE
.\"O category of the
.\"O current locale.
.BR wprintf ()
等の動作は現在のロケールの
.B LC_CTYPE
カテゴリに依存している。
.PP
.\"O If the \fIformat\fP string contains non-ASCII wide characters, the program
.\"O will only work correctly if the
.\"O .B LC_CTYPE
.\"O category of the current locale at
.\"O run time is the same as the
.\"O .B LC_CTYPE
.\"O category of the current locale at
.\"O compile time.
.\"O This is because the
\fIformat\fP 文字列が ASCII 以外のワイド文字を含んでいる場合、
実行時のロケールの
.B LC_CTYPE
カテゴリがコンパイル時の
.B LC_CTYPE
カテゴリと
一致している場合にのみプログラムは正常に動作する。これは
.I wchar_t
.\"O representation is platform- and locale- dependent.
.\"O (The glibc represents
.\"O wide characters using their Unicode (ISO-10646) code point, but other
.\"O platforms don't do this.
.\"O Also, the use of ISO C99 universal character names
.\"O of the form \\unnnn does not solve this problem.)
の表現がロケールやプラットホームに依存していることに原因がある。
(glibc ではワイド文字として Unicode (ISO-10646) のコードポイントを
使用している。他のプラットホームではそうではない。同様に
ISO C99 の \\unnnn 形式の汎用文字名称はこの問題を解決しない。)
.\"O Therefore, in
.\"O internationalized programs, the \fIformat\fP string should consist of ASCII
.\"O wide characters only, or should be constructed at run time in an
.\"O internationalized way (e.g., using
.\"O .BR gettext (3)
.\"O or
.\"O .BR iconv (3),
.\"O followed by
.\"O .BR mbstowcs (3)).
このため国際化されたプログラムでは \fIformat\fP 文字列を ASCII ワイド
文字のみにするか、実行時に国際化された方法で構成する必要がある
(例えば
.BR gettext ()
と
.BR iconv ()
や
.BR mbstowcs ()
を組み合わて使用する)。
.\"O .SH "SEE ALSO"
.SH 関連項目
.BR fprintf (3),
.BR fputwc (3),
.BR fwide (3),
.BR printf (3),
.BR snprintf (3)
.\" .BR wscanf (3)