| 標準/拡張機能 | C/C++ | 依存項目 |
|---|---|---|
ISO C |
両方 |
#include <stdio.h>
char *fgets(char * __restrict__string, int n, FILE * __restrict__stream);
#define _OPEN_SYS_UNLOCKED_EXT 1
#include <stdio.h>
char *fgets_unlocked(char * __restrict__string, int n, FILE * __restrict__stream);stream で指定されるストリームからマルチバイトを読み取り、フ ァイル位置標識によって示される位置から始まる、string で指定される配列に入れます。読み取りは、読み取られた文字数が n-1 に等しくなるまでか、改行文字 (¥n) までか、または最初にくるストリームの最後まで、続けられます。fgets() 関数は、結果を string に保管し、ストリングの終わりに NULL 文字 (¥0) を追加します。読み取られたなら、string には改行文字が含まれます。
fgets() 関数は、type=record または type=blocked を使用してオープンしたファイルで サポートされません。
fgets() には、書き込みの直後に読み取り、または読み取りの直後に 書き込みを行うための読み取り操作と同じ制約事項があります。書き込みと後続の読み取りの間には、介入フラッシュまたは位置変更が 必要です。読み取りと後続の書き込みの間でも、EOF に達していない限り、介入フラッシュまたは位置変更が必要です。
fgets_unlocked() は、スレッド・セーフでないことを除いて、機能的に fgets() と 等価です。この関数をマルチスレッドのアプリケーション内で安全に使用できるのは、 flockfile() 関数または ftrylockfile() 関数のどちらかへの呼び出しが成功した後のように、 呼び出しスレッドが (FILE*) オブジェクトを所有している間に、この関数を呼び出す場合だけです。
正常に実行された場合、fgets() は、string バッファーへのポインターを戻します。
正常に実行されなかった場合、fgets() は、失敗を示す NULL を戻します。
n が 0 以下の場合は、ドメイン・エラーを示します。errno には失敗の原因を示す EDOM が設定されます。
n が 1 の場合は、有効な結果を示します。つまり、ストリング・バッファーには NULL 終了文字しかないことを意味します。ファイルからは何も物理的に読まれていません (そのような操作でも、読み取り操作であると見なされます。したがって、介入フラッシュや再位置決め操作が最初になければ、直後で書き込み操作を行う ことはできません)。
n が 1 より大きい場合、fgets() が失敗するのは、入出力エラーが起きたか、または EOF に達したときだけであり、その場合、ファイルからデータは読み取られません。
読み取りエラーと EOF を区別するには、ferror() 関数と feof() 関数を 使用します。データの最後のバイトを「超えて」読み取ろうとしたときのみ、EOF に達することに注意してください。 データの最後のバイトまで (最後のバイトを含む) 読み取ると、EOF 標識はオンになりません。
データがストリング・バッファーに既に読み取られた後で EOF に 達した場合は、fgets() は、ストリング・バッファーを指すポインターを戻し、正常終了したことを示します。次の呼び出しは、データを読み取らずに EOF に達するため、NULL が戻される結 果となります。
⁄* CELEBF18
This example gets a line of input from a data stream.
It reads no more than MAX_LEN - 1 characters, or up
to a new-line character, from the stream.
*⁄
#include <stdio.h>
#define MAX_LEN 100
int main(void)
{
FILE *stream;
char line[MAX_LEN], *result;
stream = fopen("myfile.dat","r");
if ((result = fgets(line,MAX_LEN,stream)) != NULL)
printf("The string is %s¥n", result);
if (fclose(stream))
printf("fclose error¥n");
}