fread() - 項目の読み取り

標準

形式

#include <stdio.h>

size_t fread(void * __restrict__buffer, size_t size, size_t count, FILE * __restrict__stream);

#define _OPEN_SYS_UNLOCKED_EXT 1
#include <stdio.h>

size_t fread_unlocked(void * __restrict__buffer, size_t size, 
                      size_t count, FILE * __restrict__stream);

機能説明

stream で指定される入力ストリームから size 長の count 項目まで読み取り、それらを指定された buffer へ保管します。ファイル位置標識は、読み取られたバイト数だけ前に進みます。

読み取り操作中にエラーが発生した場合は、未定義なファイル位置標識となります。部分的にエレメントが読まれた場合は、未定義なエレメントの値となります。

レコード入出力に fread() を使用するときは、バイト数を取得するために、size を 1 に設定し、レコードについて予期されている最大長に count を設定してください。レコード入出力を使用している場合は、count を無視して、1 レコードのみを読み取ります。

ブロック入出力に fread() を使用するときは、バイト数を取得するために、size を 1 に設定し、ブロックについて予期されている最大長に count を設定してください。ブロック入出力を使用している場合は、count を無視して、1 ブロックのみを読み取ります。

fread() には、書き込みの直後に読み取り、または読み取りの直後に 書き込みを行うための読み取り操作と同じ制約事項があります。書き込みと後続の読み取りの間には、介入フラッシュまたは位置変更が 必要です。読み取りと後続の書き込みの間でも、EOF に達していない限り、介入フラッシュまたは位置変更が必要です。

fread_unlocked() は、スレッド・セーフでないことを除いて、機能的に fread() と 等価です。この関数をマルチスレッドのアプリケーション内で安全に使用できるのは、 flockfile() 関数または ftrylockfile() 関数のどちらかへの呼び出しが成功した後のように、 呼び出しスレッドが (FILE*) オブジェクトを所有している間に、この関数を呼び出す場合だけです。

戻り値

fread() は、正常に読み取られた完全項目数を戻します。

size または count が 0 の場合、fread() は 0 を 戻し、配列の内容とストリームの状態は変更されないままになります。レコード入出力およびブロック入出力の場合、完全項目数は count より小さい可能性があります。しかし、この結果は必ずしも エラーが発生したことを示すものではありません。

物理ファイル・システムがディレクトリーからの単純読み取りをサポートしていない場合、fread() は、ディレクトリーに 0 が使用されている場合は、0 を戻します。ユーザーは、代わりに Opendir() および readdir() を使用する必要があります。

読み取りエラーと EOF を区別するには、ferror() 関数と feof() 関数を 使用します。データの最後のバイトを「超えて」読み取ろうとしたときのみ、EOF に達することに注意してください。 データの最後のバイトまで (最後のバイトを含む) 読み取ると、EOF 標識はオンになりません。

例

/* CELEBF38

   This example attempts to read NUM_ALPHA characters from the
   file myfile.dat.
   If there are any errors with either &fread. or &fopen., a
   message is printed.

 */
#include <stdio.h>
#define NUM_ALPHA  26

int main(void)
{
  FILE * stream;
  int num;       /* number of characters read from stream */

  /* Do not forget that the '¥0' char occupies one character too! */
  char buffer[NUM_ALPHA + 1];
  buffer[NUM_ALPHA] = '¥0';

  if (( stream = fopen("myfile.dat", "r"))!= NULL )
  {
    num = fread( buffer, sizeof( char ), NUM_ALPHA, stream );
    if (num == NUM_ALPHA) {  /* fread success */
      printf( "Number of characters read = %i¥n", num );
      printf( "buffer = %s¥n", buffer );
      fclose( stream );
    }
    else {  /* fread failed */
      if ( ferror(stream) )         /* possibility 1 */
        printf( "Error reading myfile.dat" );
      else if ( feof(stream)) {     /* possibility 2 */
        printf( "EOF found¥n" );
        printf( "Number of characters read %d¥n", num );
        printf( "buffer = %.*s¥n", num, buffer);
      }
    }
  }
  else
    printf( "Error opening myfile.dat" );
}

関連情報

• stdio.h — 標準入出力
• fopen() - ファイルのオープン
• freopen() - オープン・ファイルの宛先変更
• fwrite() - 項目の書き込み