| 標準/拡張機能 | C/C++ | 依存項目 |
|---|---|---|
ISO C 改訂 |
両方 |
#include <wchar.h>
wchar_t *fgetws(wchar_t * __restrict__wcs, int n, FILE * __restrict__stream);
#define _OPEN_SYS_UNLOCKED_EXT 1
#include <wchar.h>
wchar_t *fgetws_unlocked(wchar_t * __restrict__wcs,
int n, FILE * __restrict__stream);n で指定したワイド文字の数よりも多くても 1 つ少ない数の文字数を、stream が指すストリームから wcs が指す配列に読み取ります。改行ワイド文字 (保存された) または EOF の後は、もうワイド文字は読み取ら れません。NULL ワイド文字は、最後のワイド文字が配列へ読み取られた直後に書かれます。
fgetws() 関数は、ファイル位置が未定義のとき、エラーがない限りは ファイル位置を進めます。
このワイド文字関数の動作は、現行ロケールの LC_CTYPE カテゴリーの影響を受けます。 カテゴリーを変更すると、未定義の結果が発生する可能性があります。
非ワイド文字関数を fgetws() と共に使用すると、未定義の動作が 生じる結果となります。その理由は、fgetws() はマルチバイト文字全体を処理し、非ワイド文字 の「中」にマルチバイト文字があることを予期しないことです。また、fgetws() は、状態情報が既に設定されていることを予期します。fgetc() や fputc() などの関数はこのような規則に従わないので、これらの関数の結果は、fgetws() の予期と一致しません。
fgetws() には、書き込みの直後に読み取り、または読み取りの直後に 書き込みを行うための読み取り操作と同じ制約事項があります。書き込みと後続の読み取りの間には、介入フラッシュまたは位置変更が 必要です。読み取りと後続の書き込みの間でも、EOF に達していない限り、介入フラッシュまたは位置変更が必要です。
fgetws_unlocked() は、スレッド・セーフでないことを除いて、機能的に fgetws() と 等価です。この関数をマルチスレッドのアプリケーション内で安全に使用できるのは、 flockfile() 関数または ftrylockfile() 関数のどちらかへの呼び出しが成功した後のように、 呼び出しスレッドが (FILE*) オブジェクトを所有している間に、この関数を呼び出す場合だけです。
正常に実行された場合、fgetws() は wcs の新規値を戻します。
EOF が検出され、ワイド文字が配列に読み取られなかった場合は、配列の内容は変更されないままで、fgetws() は、NULL ポインターを戻します。
操作中に、読み取りエラーまたはエンコード・エラーが発生した場合は、配列の内容は不明確で、fgetws() は NULL ポインターを戻します。エンコード・エラーは、ワイド文字をマルチバイト文字へ変換するときに起きるものです。これが起きた場合は、errno は EILSEQ に設定され、fgetws() は NULL を戻します。
n が 0 以下の場合は、ドメイン・エラーを示します。errno には失敗の原因を示す EDOM が設定されます。
n が 1 の場合は、有効な結果を示します。つまり、ストリング・バッファーには NULL 終了文字しかないことを意味します。ファイルからは何も物理的に読まれていません (そのような操作でも、読み取り操作であると見なされます。したがって、介入フラッシュや再位置決め操作が最初になければ、直後で書き込み操作を行う ことはできません)。
n が 1 より大きい場合、fgets() が失敗するのは、入出力エラーが起きたか、または EOF に達したときだけであり、その場合、ファイルからデータは読み取られません。どのエラーが起きたかを知るには、feof() または ferror() 関数の どちらかを使用してください。データがストリング・バッファーに既に読み取られた後で EOF に 達した場合は、fgetws() は、ストリング・バッファーを指すポインターを戻し、正常終了したことを示します。次の呼び出しは、データを読み取らずに EOF に達するため、NULL が戻される結 果となります。
読み取りエラーと EOF を区別するには、ferror() 関数と feof() 関数を 使用します。データの最後のバイトを「超えて」読み取ろうとしたときのみ、EOF に達することに注意してください。 データの最後のバイトまで (最後のバイトを含む) 読み取ると、EOF 標識はオンになりません。
⁄* CELEBF20 *⁄
#include <errno.h>
#include <stdio.h>
#include <stdlib.h>
#include <wchar.h>
int main(void)
{
FILE *stream;
wchar_t wcs[100];
wchar_t *ptr;
if ((stream = fopen("myfile.dat", "r")) == NULL) {
printf("Unable to open file¥n");
exit(1);
}
errno = 0;
ptr = fgetws(wcs, 100, stream);
if (ptr == NULL) {
if (errno == EILSEQ) {
printf("An invalid wide character was encountered.¥n");
exit(1);
}
else if (feof(stream))
printf("end of file reached¥n");
else
perror("read error");
}
printf("wcs=¥"%ls¥"¥n", wcs);
fclose(stream);
}