fwprintf() — ワイド文字としてのデータのフォーマット設定とストリームへの書き込み

フォーマット

#include <stdio.h>
#include <wchar.h>
int fwprintf(FILE *stream, const wchar_t *format, argument-list);

言語レベル

ANSI

スレッド・セーフ

はい

ロケール依存

この関数の振る舞いは、LOCALETYPE(*LOCALEUCS2) または LOCALETYPE(*LOCALEUTF) がコンパイル・コマンドに対して指定されている場合は、現行ロケールの LC_CTYPE および LC_NUMERIC カテゴリーの影響を受ける可能性があります。この関数は、コンパイル・コマンドに対して LOCALETYPE(*CLD) が指定されている場合には使用できません。詳細については、CCSID およびロケールの理解を参照してください。

統合ファイル・システム・インターフェース

この関数は、コンパイル・コマンドに対して SYSIFCOPT(*NOIFSIO) が指定されている場合には使用できません。

ワイド文字関数

詳細については、ワイド文字を参照してください。

説明

fwprintf() 関数は、format により示されたワイド・ストリングの制御下で、stream により示されたストリームに出力を書き込みます。書式ストリングは、後続の引数が出力用にどのように変換されるかを指定します。

fwprintf() 関数は、書式中の対応するワイド文字指定子に応じて、argument-list 内の各エントリーを変換します。

書式に対して引数が不十分な場合、振る舞いは予期できません。引数が残っているのに、書式がすべて使用されている場合、fwprintf() 関数は余分の引数を評価しますが、それ以外の場合は無視します。 fwprintf() 関数は、書式ストリングの終わりになると戻ります。

書式はゼロ以上のディレクティブで構成されています。一般にはワイド文字 (% 以外) および変換指定です。変換指定は、書式ストリングでワイド文字ストリングにより置換されたかのように処理されます。ワイド文字ストリングはゼロ以上の後続の引数を取り出し、該当する場合は、対応する変換指定子に応じてその引数を変換した結果です。 fwprintf() 関数は次に、展開されたワイド文字書式ストリングを出力ストリームに書き込みます。

fwprintf() 関数の書式には、printf() の書式ストリングと同じ形式と機能がありますが、以下の点が異なります。

%c (l 接頭部なし) は、btowc() 関数を呼び出して変換したかのように、整数引数を wchar_t に変換します。
%s (l 接頭部なし) は、mbrtowc() 関数を呼び出して変換したかのように、マルチバイト文字の配列を wchar_t の配列に変換します。精度に対して、より短い出力が指定されていない限り、配列は終了 NULL 文字に達するまで (終了 NULL 文字は含まれません) 書き込まれます。
%ls および %S は wchar_t の配列を書き込みます。この配列は、終了ヌル文字に達するまで書き込まれます (終了ヌル文字自身は書き込まれません) 。ただし、より短い出力が精度に指定されている場合は除きます。
%c、%s、%ls、および %S に対して指定された任意の幅すなわち精度は、バイト数ではなく、文字数を示します。

変換指定が無効な場合、その振る舞いは予期できません。

任意の引数またはポイントが和集合または集合の場合 (%s 変換を使用した char 型配列、 %ls 変換を使用した wchar_t 型配列、または %p 変換を使用したポインターを除く)、振る舞いは予期できません。

いかなる場合も、存在していないフィールド幅または短いフィールド幅で、フィールドが切り捨てられることはありません。変換結果がフィールド幅よりも広い場合、そのフィールドは変換結果を含めるように拡張されます。

注: ワイド文字を書き込む場合、ファイルはバイナリー・モードでオープンするか、o_ccsid または codepage パラメーターでオープンする必要があります。これにより、ワイド文字に対して変換が発生しないことが保証されます。

戻り値

fwprintf() 関数は、送信されたワイド文字の数を戻します。出力エラーが発生すると、負の値を戻します。

例

#include <stdio.h>
#include <wchar.h>
#include <locale.h>
int count [10] = {1, 5, 8, 3, 0, 3, 5, 6, 8, 10};
int main(void)
{
   int i,j;
   FILE *stream;                      /* Open the stream for writing */ 
   if (NULL == (stream = fopen("/QSYS.LIB/LIB.LIB/WCHAR.FILE/WCHAR.MBR","wb")))
      perror("fopen error"); 
   for (i=0; i < sizeof(count) / sizeof(count[0]); i++)
   {
      for (j = 0; j < count[i]; j++)
         fwprintf(stream, L"*");      /* Print asterisk              */ 
         fwprintf(stream, L"¥n");     /* Move to the next line       */
   }
   fclose (stream);
}
/* The member WCHAR of file WCHAR will contain:
   *
   *****
   ********
   ***
   ***
   *****
   ******
   ********
   **********
 */

Unicode の例

#include <stdio.h>
#include <stdlib.h>
#include <locale.h>
/* This program is compile LOCALETYPE(*LOCALEUCS2) and             */
/* SYSIFCOPT(*IFSIO)                                               */
int main(void)
{
    FILE *stream;
    wchar_t wc = 0x0058;     /* UNICODE X */
    char c1 = 'c';
    char *s1 = "123";
    wchar_t ws[4];
    setlocale(LC_ALL,
     "/QSYS.LIB/EN_US.LOCALE"); /* a CCSID 37 locale */
    ws[0] = 0x0041;        /* UNICODE A   */
    ws[1] = (wchar_t)0x0042;        /* UNICODE B   */
    ws[2] = (wchar_t)0x0043;        /* UNICODE C   */
    ws[3] = (wchar_t)0x0000;

    stream = fopen("myfile.dat", "wb+");

    /* lc and ls take wide char as input and just copies then  */
    /* to the file.  So the file would look like this        */
    /* after the below fwprintf statement:                   */
    /* 0058002000200020004100420043                          */
    /* 0020 is UNICODE blank                                 */

    fwprintf(stream, L"%lc   %ls",wc,ws);
    /* c and s take multibyte as input and produce UNICODE   */
    /* In this case c1 and s1 are CCSID 37 characters based  */
    /* on the setlocale above.  So the characters are        */
    /* converted from CCSID 37 to UNICODE and will look      */
    /* like this in hex after the following fwprintf         */
    /* statement:   0063002000200020003100320033             */
    /* 0063 is a UNICODE c  0031 is a UNICODE 1 and so on    */

    fwprintf(stream, L"%c   %s",c1,s1);

    /* Now lets try width and precision.  6ls means write  */
    /* 6 wide characters so we will pad with 3 UNICODE     */
    /* blanks and %.2s means write no more then 2 wide     */
    /* characters.  So we get an output that looks like    */
    /* this:  00200020002000410042004300310032             */

    fwprintf(stream, L"%6ls%.2s",ws,s1);
}