fgetws() — ストリームのワイド文字のストリングの読み取り

フォーマット

#include <wchar.h>
#include <stdio.h>
wchar_t *fgetws(wchar_t *wcs, int n, FILE *stream);

言語レベル

ANSI

スレッド・セーフ

はい

ロケール依存

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

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

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

ワイド文字関数

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

説明

fgetws() 関数は、 stream が指すストリームからワイド文字を読み取ります。読み取られる文字数の上限は n より 1 つ少ない数となります。fgetws() 関数は WEOF の後か、または改行ワイド文字 (これは、保持されます) を読み取った後、文字の読み取りを停止します。また、最後のワイド文字が配列へ読み取られた直後に NULL ワイド文字を追加します。 fgetws() 関数はエラーがない限り、ファイル位置を進めます。エラーが発生した場合、ファイル位置は予期できません。

非ワイド文字関数を fgetws() 関数と共に同じストリーム上で使用すると、予期しない振る舞いが生じる結果となります。 fgetws() 関数を呼び出した後、WEOF に達しない限り、ストリームの書き込み関数を呼び出す前にバッファーをフラッシュするか、ストリーム・ポインターの位置を変更してください。ストリームに対する書き込み操作の後、fgetws() 関数を呼び出す前にバッファーをフラッシュするか、ストリーム・ポインターの位置を変更してください。

注: 同じストリームに対する後続の読み取り操作間で現行ロケールが変更された場合は、未定義の結果が発生することがあります。

戻り値

正常終了の場合は、fgetws() 関数はワイド文字ストリング wcs を指すポインターを戻します。ワイド文字が wcs に読み取られる前に WEOF が検出された場合は、wcs の内容は変更されないままで、fgetws() 関数は NULL ポインターを戻します。データがストリング・バッファーにすでに読み取られた後で WEOF に達した場合は、fgetws() 関数はストリング・バッファーを指すポインターを戻し、正常終了したことを示します。この後に続く呼び出しは、データを読み取らずに WEOF に達するため、NULL を戻します。

読み取りエラーが発生すると、wcs の内容は確定できず、fgetws() 関数は NULL を戻します。エンコード・エラーが発生した場合 (ワイド文字をマルチバイト文字に変換中に)、fgetws() 関数は errno に EILSEQ を設定し、NULL を戻します。

n が 1 に等しいと、wcs バッファーは最後の NULL 文字分の空きしかなく、ストリームからは何も読み取られません。 (そのような操作でも、読み取り操作であるとみなされます。したがって、最初にバッファーがフラッシュされたり、ストリーム・ポインターが位置変更されない限り、直後で書き込み操作を行うことはできません)。 n が 1 より大きいときは、入出力エラーが起こるか、データがストリームから読み取られる前に WEOF に達した場合にのみ、fgetws() 関数が失敗します。

ferror() および feof() 関数を使用して読み取りエラーと WEOF とを区別します。 WEOF に達するのは、データの最後のバイトを超えて読み取ろうとした場合のみです。データの最後のバイトまで (最後のバイトを含む) 読み取っても、WEOF 標識はオンになりません。

fgetws() の errno 値について詳しくは、fgetwc() — ストリームのワイド文字の読み取りを参照してください。

例

この例はファイルをオープンし、ファイルの内容を読み取ってからそのファイルの内容を出力します。

#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
 
int main(void)
{
   FILE    *stream;
   wchar_t  wcs[100];
 
   if (NULL == (stream = fopen("fgetws.dat", "r"))) {
      printf("Unable to open: ¥"fgetws.dat¥"¥n");
      exit(1);
   }
 
   errno = 0;
   if (NULL == fgetws(wcs, 100, stream)) {
      if (EILSEQ == errno) {
         printf("An invalid wide character was encountered.¥n");
         exit(1);
      }
      else if (feof(stream))
              printf("End of file reached.¥n");
           else
              perror("Read error.¥n");
   }
   printf("wcs = ¥"%ls¥"¥n", wcs);
   fclose(stream);
   return 0;
 
   /************************************************************
      Assuming the file fgetws.dat contains:
 
      This test string should not return -1
 
      The output should be similar to:
 
      wcs = "This test string should not return -1"
   ************************************************************/
}