fwscanf() — ワイド文字を使用したストリームからのデータの読み取り

フォーマット

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

言語レベル

ANSI

スレッド・セーフ

はい

ロケール依存

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

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

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

ワイド文字関数

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

説明

fwscanf() 関数は、format により指されたワイド・ストリングの制御下で、stream により指されたストリームから入力データを読み取ります。書式ストリングは許容入力シーケンスおよびこれらが割り当てられるための変換方法を指定します。 変換済み入力データを受信するために、fwscanf() 関数は後続の引数をオブジェクトを指すポインターとして使用します。

argument-list の各引数は、書式の型指定子に対応する型を持つ変数を指さなければなりません。

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

書式は、ゼロ以上のディレクティブ、すなわち、1 つ以上の空白文字および普通のワイド文字 (% と空白文字は含まない) または変換指定で構成されます。各変換指定の先頭には、% が入ります。

この書式には scanf() 関数の書式ストリングと同じ形式と機能がありますが、以下の点が異なります。
  • %c (l 接頭部なし) は、wcrtomb() の呼び出しにより変換したかのように、1 つ以上の wchar_t 文字 (文字数は精度によって異なります) をマルチバイト文字に変換します。
  • %lc および %C は、1 つ以上の wchar_t 文字 (文字数は精度によって異なります) を wchar_t の配列に変換します。
  • %s (l 接頭部なし) は、wcrtomb() 関数の呼び出しにより変換したかのように、空白文字ではない wchar_t 文字のシーケンスをマルチバイト文字に変換します。 配列には NULL 終了文字が含まれます。
  • %ls および %S は wchar_t の配列 (NULL 終了ワイド文字を含む) を wchar_t の配列にコピーします。

データが stdin のもので、stdin が上書きされていなかった場合、そのデータはジョブの CCSID にあると仮定されます。データは書式仕様の要求により変換されます。 読み取られているファイルがファイル・モード rb でオープンされない場合には、無効な変換エラーが発生することがあります。

変換指定が無効な場合、その振る舞いは予期できません。 入力中に fwscanf() 関数がファイル終了になった場合、変換は終了します。 fwscanf() 関数が現行ディレクティブ (先頭の空白文字が許可されている場合は、先頭の空白文字以外) に一致するすべての文字を読み取る前にファイル終了が発生すると、入力障害により現行ディレクティブの実行が終了します。 それ以外の場合は、現行ディレクティブの実行がマッチング失敗により終了しない限り、それに続くディレクティブ (%n がある場合は、これ以外) の実行は入力失敗により終了します。

ディレクティブによりマッチングされない限り、fwscanf() 関数は末尾の空白文字 (改行ワイド文字を含む) を未読のままにします。%n ディレクティブによるもの以外の、リテラル・マッチと抑止された代入の正常終了を判別することはできません。

戻り値

fwscanf() 関数は、割り当てられた入力項目数を戻しますが、これは、以前のマッチングが失敗した場合、提供された数より少なくなることがあります。

変換の前に入力障害が起こった場合、fwscanf() 関数は EOF を戻します。

例

次の例は、入力用にファイル myfile.dat をオープンし、その後このファイルをストリング、long 型整数値、文字、および浮動小数点値について走査します。 
#include <stdio.h>
#include <wchar.h>
 
#define  MAX_LEN       80
 
int main(void)
{
   FILE *stream;
   long l;
   float fp;
   char s[MAX_LEN+1];
   char c;
 
   stream = fopen("myfile.dat", "r");
 
    /* Read data from file. */
 
   fwscanf(stream, L"%s", &s[0]);
   fwscanf(stream, L"%ld", &l);
   fwscanf(stream, L"%c", &c);
   fwscanf(stream, L"%f", &fp);
 
   printf("string = %s¥n", s);
   printf("long integer = %ld¥n", l);
   printf("char = %c¥n", c);
   printf("float = %f¥n", fp);
   return 0;
 
   /***********************************************
      If myfile.dat contains:
      abcdefghijklmnopqrstuvwxyz 343.2.
 
      The output should be:
 
      string = abcdefghijklmnopqrstuvwxyz
      long integer = 343
      char = .
      float = 2.000000
   ***********************************************/
}

Unicode の例

次の例は unicode.dat から Unicode ストリングを読み取り、それを画面に出力します。 この例は、LOCALETYPE(*LOCALEUCS2) SYSIFCOPT(*IFSIO) でコンパイルされています。 
#include   <stdio.h>
#include   <wchar.h>
#include   <locale.h>
void main(void)
{
FILE *stream;
wchar_t buffer[20];
stream=fopen("unicode.dat","rb");

fwscanf(stream,L"%ls", buffer);
wprintf(L"The string read was :%ls\n",buffer);

fclose(stream);
}

/* If the input in unicode.dat is :
 ABC
 and ABC is in unicode which in hex would be 0x0041, 0x0042, 0x0043
 then the output will be similar to:
 The string read was :ABC
*/

関連情報

親トピック: ライブラリー関数