freopen、_wfreopen

[アーティクル]
08/09/2011

ファイルポインターを再度割り当てます。これらの関数のセキュリティを強化したバージョンについては、「freopen_s、_wfreopen_s」を参照してください。

FILE *freopen( 
   const char *path,
   const char *mode,
   FILE *stream 
);
FILE *_wfreopen( 
   const wchar_t *path,
   const wchar_t *mode,
   FILE *stream 
);

パラメーター

path
新しいファイルのパス。
mode
アクセス許可の種類。
stream
FILE 構造体へのポインター。

戻り値

これらの各関数は、新しく開かれたファイルへのポインターを返します。エラーが発生した場合、元のファイルが閉じられ、関数が NULL ポインター値を返します。 path、mode、または stream が null ポインターの場合、あるいは filename が空の文字列の場合、「パラメーターの検証」に説明されているように、これらの関数は無効なパラメーターハンドラーを呼び出します。実行の継続が許可された場合、これらの関数は errno を EINVAL に設定し、NULL を返します。

エラーコードの詳細については、「_doserrno、errno、_sys_errlist、および _sys_nerr」を参照してください。

解説

これらの関数にはセキュリティが強化されたバージョンがあります。「freopen_s、_wfreopen_s」を参照してください。

freopen 関数は、現在 stream に関連付けられているファイルを閉じ、path で指定したファイルに stream を再度割り当てます。ワイド文字を扱う場合は、_freopen ではなく _wfreopen を使用します。_wfreopen の場合、path 引数および mode 引数にはワイド文字列を指定します。それ以外では、_wfreopen と _freopen の動作は同じです。

汎用テキストルーチンのマップ

TCHAR.H のルーチン	_UNICODE および _MBCS が未定義の場合	_MBCS が定義されている場合	_UNICODE が定義されている場合
_tfreopen	freopen	freopen	_wfreopen

freopen は、通常、既に開いている stdin、stdout、および stderr の各ファイルをユーザー指定のファイルにリダイレクトするために使用します。 stream に関連付けられた新しいファイルは、mode で開かれます。mode は、ファイルに要求するアクセスの種類を指定する次のような文字列です。

"r"
読み出し用に開きます。ファイルが存在しない場合や見つからない場合、freopen 呼び出しは失敗します。
"w"
書き込み用に空のファイルを開きます。指定したファイルが既に存在すると、そのファイルの内容は破棄されます。
"a"
末尾に書き込みができるようにファイルを開きます (追加モード)。ファイルに新しいデータを書き込むとき、EOF マーカーは削除されません。ファイルが存在しない場合は、先にファイルを作成します。
"r+"
読み出しと書き込みの両方のモードで開きます。ファイルが存在している必要があります。
"w+"
読み出しと書き込みの両方のモードで空のファイルを開きます。指定したファイルが既に存在すると、そのファイルの内容は破棄されます。
"a+"
読み出しと追加の両方のモードでファイルを開きます。追加時には、ファイルに新しいデータを書き込む前に EOF マーカーを削除し、書き込みが終了すると EOF マーカーを復元します。ファイルが存在しない場合は、先にファイルを作成します。

アクセスの種類が "w" および "w+" の場合は既存のファイルを破棄する可能性があるので、使用時には注意が必要です。

アクセスの種類が "a" または "a+" の場合にファイルを開くと、すべての書き込み操作はファイルの末尾から行われます。ファイルポインターは fseek 関数または rewind 関数で移動できますが、書き込み操作の前に必ずファイルの終端に戻されます。したがって、既存のデータは上書きされません。

"a" モードでは、ファイルへの追加の前に EOF マーカーは削除されません。追加が行われても、MS-DOS TYPE コマンドでは元の EOF マーカーまでのデータしか表示されず、ファイルに追加されたデータは表示されません。 "a+" モードでは、ファイルへの追加の前に EOF マーカーが削除されます。追加が終了すると、MS-DOS の TYPE コマンドでファイル内すべてのデータが表示されます。 Ctrl + Z EOF マーカーで終了するストリームファイルに追加するには、"a+" モードを使用する必要があります。

"r+"、"w+"、または "a+" のいずれかのアクセスの種類を指定すると、読み取りと書き込みの両方を行うことができます (ファイルは "更新" モードで開きます)。ただし、読み出しと書き込みを切り替えるには、その前に fsetpos、fseek、rewind のいずれかの関数を実行する必要があります。必要に応じて、fsetpos 関数または fseek 関数には現在位置を指定できます。上記の値に加え、mode 文字列に次のいずれかの文字を指定すると、改行文字の変換モードを指定できます。

t
ファイルをテキスト (変換) モードで開きます。このモードでは、入力時にキャリッジリターンとラインフィード (CR-LF: carriage return–linefeed) が単独のラインフィード (LF: linefeed) 文字に変換され、出力時に LF 文字が CR-LF に変換されます。また、Ctrl + Z は入力時に EOF (EOF: end-of-file) 文字として解釈されます。ファイルを読み取りモードで開いた場合、または "a+" を指定して読み取りと書き込みの両方のモードで開いた場合、ランタイムライブラリによってファイル末尾の Ctrl + Z が確認され、削除できる場合は削除されます。この処理が行われるのは、ファイル内を fseek 関数および ftell 関数を使用して移動すると、ファイル末尾付近で fseek が正しく動作しないことがあるからです。 t オプションは、Microsoft 拡張機能なので、ANSI 互換が必要な場合は使用しないでください。
b
ファイルをバイナリ (非変換) モードで開きます。上記の変換は行われません。

t または b を mode に指定しないと、既定の変換モードは _fmode グローバル変数によって定義されます。 t または b を引数の先頭に指定すると、エラーが発生して NULL が返されます。

テキストモードとバイナリモードについては、「テキストモードとバイナリモードのファイル入出力」を参照してください。

必要条件

機能	必須ヘッダー
freopen	<stdio.h>
_wfreopen	<stdio.h> または <wchar.h>

互換性の詳細については、「C ランタイムライブラリ」の「互換性」を参照してください。

使用例

// crt_freopen.c
// compile with: /W3
// This program reassigns stderr to the file
// named FREOPEN.OUT and writes a line to that file.
#include <stdio.h>
#include <stdlib.h>

FILE *stream;

int main( void )
{
   // Reassign "stderr" to "freopen.out": 
   stream = freopen( "freopen.out", "w", stderr ); // C4996
   // Note: freopen is deprecated; consider using freopen_s instead

   if( stream == NULL )
      fprintf( stdout, "error on freopen\n" );
   else
   {
      fprintf( stdout, "successfully reassigned\n" ); fflush( stdout );
      fprintf( stream, "This will go to the file 'freopen.out'\n" );
      fclose( stream );
   }
   system( "type freopen.out" );
}