fopen、_wfopen

更新 : 2007 年 11 月

ファイルを開きます。これらの関数のセキュリティを強化したバージョンについては、「fopen_s、_wfopen_s」を参照してください。

FILE *fopen( 
   const char *filename,
   const char *mode 
);
FILE *_wfopen( 
   const wchar_t *filename,
   const wchar_t *mode 
);

パラメータ

• filename
  ファイル名。

• mode
  アクセス許可の種類。

戻り値

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

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

解説

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

fopen 関数は、filename で指定されたファイルを開きます。ワイド文字を扱う場合は、fopen ではなく _wfopen を使用します。_wfopen の場合、引数にはワイド文字列を指定します。引数の指定以外では、_wfopen と fopen の動作は同じです。単に _wfopen を使用する場合、ファイル ストリームで使用されるコード化文字セットには影響しません。

fopen は、実行時にファイル システムで有効なパスを受け取ります。UNC パス、および割り当てられたネットワーク ドライブを含むパスは、コードを実行するシステムが実行時に共有ネットワーク ドライブまたは割り当てられたネットワーク ドライブにアクセスする限り、fopen で受け取られます。実行時環境で使用できるドライブ、パス、またはネットワーク共有を判断されないように fopen のパスを構築する場合は、特に注意する必要があります。

ファイルでその他の操作を実行する前には、必ず戻り値をチェックしてポインタが NULL かどうかを確認します。エラーが発生した場合、errno グローバル変数が設定され、特定のエラー情報を取得するために使用されることがあります。詳細については、「errno、_doserrno、_sys_errlist、および _sys_nerr」を参照してください。

Visual C++ 2005 では、fopen は Unicode のファイル ストリームをサポートします。必要なエンコーディングを指定するフラグは、新しいファイルを開いたり既存のファイルを上書きしたりすると、次のように fopen に渡されることがあります。

fopen("newfile.txt", "rw, ccs=<encoding>");

encoding に指定できる値には、UNICODE、UTF-8、および UTF16-LE があります。ファイルが既に存在し、読み取り用または追加用に開かれる場合、バイト順マーク (BOM: Byte Order Mark) を使用して適切なエンコーディングが決定されます。フラグでエンコーディングを指定する必要はありません。実際、BOM で示されたようにフラグがファイルの種類と競合する場合、このフラグは無視されます。フラグは、BOM が表示されていない場合またはファイルが新しいファイルの場合のみ使用されます。fopen に指定される各種フラグとファイルで使用されるバイト順マークで使用されるモードを次の表に示します。

Flag および BOM に基づいて使用されるエンコーディング

mode が "a, ccs=<encoding>" の場合、fopen は、最初に、読み取りと書き込みの両方が可能なモードでファイルを開こうとします。ファイルを開けた場合、BOM を読み取って、このファイルのエンコーディングを調べます。ファイルを開けなかった場合は、ファイルの既定のエンコーディングが使用されます。どちらの場合も、fopen は、書き込み専用アクセスでファイルを開き直します。これは a モードにのみ適用され、a+ の場合は適用されません。

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

mode 文字列では、次のように、ファイルに要求するアクセスの種類を指定します。

• "r"
  読み出し用に開きます。ファイルが存在しない場合や見つからない場合、fopen 呼び出しは失敗します。

• "w"
  書き込み用に空のファイルを開きます。指定したファイルが既に存在すると、そのファイルの内容は破棄されます。

• "a"
  末尾に書き込みができるようにファイルを開きます (追加モード)。EOF マーカーを削除せずにファイルに新しいデータを書き込みます。ファイルが存在しない場合は、作成します。

• "r+"
  読み出しと書き込みの両方のモードで開きます。ファイルが存在している必要があります。

• "w+"
  読み出しと書き込みの両方のモードで空のファイルを開きます。指定したファイルが既に存在すると、そのファイルの内容は破棄されます。

• "a+"
  読み出しと追加の両方のモードでファイルを開きます。追加時には、ファイルに新しいデータを書き込む前に EOF マーカーが削除され、書き込みが終了すると EOF マーカーが復元します。ファイルが存在しない場合は、作成します。

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

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

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

上記の値に加え、mode に次の文字を追加すると、改行文字の変換モードを指定できます。

• t
  ファイルをテキスト (変換) モードで開きます。このモードでは、Ctrl + Z は入力時に EOF (EOF: end-of-file) 文字として解釈されます。"a+" を使用して読み取りおよび書き込みの両方のモードで開かれたファイルでは、fopen がファイル末尾に Ctrl + Z があるかどうかを確認し、削除できる場合は削除します。この処理が行われる理由は、CTRL+Z で終わるファイルの中身を fseek 関数および ftell 関数で移動するとき、ファイル末尾付近で fseek が正しく動作しないことがあるためです。

さらに、テキスト モードでは、復帰と改行の組み合わせは入力時に 1 つの改行に変換され、改行文字が出力時に復帰と改行の組み合わせに変換されます。Unicode のストリーム入出力関数が既定のテキスト モードで動作すると、入力元または出力先のストリームはマルチバイト文字のシーケンスと仮定されます。このため、Unicode ストリーム入力関数はマルチバイト文字をワイド文字に変換し、mbtowc 関数を呼び出した場合と同様の効果を得ます。同様の理由で、Unicode ストリーム出力関数は、wctomb 関数が呼び出されたかのように、ワイド文字をマルチバイト文字に変換します。

• b
  ファイルをバイナリ (無変換) モードで開きます。キャリッジ リターンとライン フィードの変換は行われません。

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

Unicode およびマルチバイトのストリーム入出力におけるテキスト モードおよびバイナリ モードの使い方の詳細については、「テキスト モードとバイナリ モードのファイル入出力」および「テキスト モードとバイナリ モードの Unicode ストリーム入出力」を参照してください。

• c
  関連付けられた filename のコミット フラグを有効にして、fflush または _flushall のいずれかが呼び出された場合に、ファイル バッファの内容がディスクに直接書き込まれるようにします。

• n
  関連付けられた filename のコミット フラグを "コミットなし" にリセットします。これは、既定の設定です。プログラムが COMMODE.OBJ にリンクされている場合、グローバル コミット フラグも上書きします。プログラムが明示的に COMMODE.OBJ にリンクされていない場合、グローバル コミット フラグの既定の設定は "コミットなし" です (「リンク オプション」参照)。

• N
  ファイルが子プロセスによって継承されないように指定します。

• S
  キャッシュがディスクからのシーケンシャル アクセスに最適化されるように指定します。ただし、シーケンシャル アクセスに限定されるわけではありません。

• R
  キャッシュがディスクからのランダム アクセスに最適化されるように指定します。ただし、ランダム アクセスに限定されるわけではありません。

• T
  ファイルを一時ファイルとして指定します。可能な場合、ファイルはディスクにフラッシュされません。

• D
  ファイルを一時ファイルとして指定します。最後のファイル ポインタが閉じられると、ファイルは削除されます。

• ccs=ENCODING
  このファイルに使用するコード化された文字セット (UTF-8、UTF-16LE、または UNICODE) を指定します。何も指定しない場合は、ANSI エンコーディングが使用されます。このオプションは Visual C++ 2005 以降で使用できます。

fopen および _fdopen で使用される mode 文字列に有効な文字は、_open および _sopen で使用する oflag 引数に次のように対応しています。

rb モードを使用していて、コードを移植する必要がなく、大量のファイルを読み込む予定があり、ネットワーク パフォーマンスを気にする必要がない場合は、Win32 メモリ マップト ファイルも省略できます。

必要条件

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

c、n、t、S、R、T、および D の各 mode オプションは、fopen および _fdopen の Microsoft 拡張機能です。ANSI 互換が必要な場合は使用しないでください。

使用例

次のプログラムでは、2 つのファイルを開きます。このプログラムでは、fclose 関数を使用して最初のファイルを閉じ、_fcloseall 関数を使用して残りのすべてのファイルを閉じます。

// crt_fopen.c
// compile with: /W3
// This program opens two files. It uses
// fclose to close the first file and
// _fcloseall to close all remaining files.

#include <stdio.h>

FILE *stream, *stream2;

int main( void )
{
   int numclosed;

   // Open for read (will fail if file "crt_fopen.c" does not exist)
   if( (stream  = fopen( "crt_fopen.c", "r" )) == NULL ) // C4996
   // Note: fopen is deprecated; consider using fopen_s instead
      printf( "The file 'crt_fopen.c' was not opened\n" );
   else
      printf( "The file 'crt_fopen.c' was opened\n" );

   // Open for write 
   if( (stream2 = fopen( "data2", "w+" )) == NULL ) // C4996
      printf( "The file 'data2' was not opened\n" );
   else
      printf( "The file 'data2' was opened\n" );

   // Close stream if it is not NULL 
   if( stream)
   {
      if ( fclose( stream ) )
      {
         printf( "The file 'crt_fopen.c' was not closed\n" );
      }
   }

   // All other files are closed: 
   numclosed = _fcloseall( );
   printf( "Number of files closed by _fcloseall: %u\n", numclosed );
}

The file 'crt_fopen.c' was opened
The file 'data2' was opened
Number of files closed by _fcloseall: 1

次のプログラムでは、ファイルを作成します (ファイルが存在する場合は上書きします)。テキストモードでは、Unicode エンコーディングを使用します。その後、2 つの文字列をファイルに書き込み、ファイルを閉じます。_wfopen_test.xml というファイルが出力されます。このファイルには、出力セクションのデータが格納されます。

// crt__wfopen.c
// compile with: /W3
// This program creates a file (or overwrites one if
// it exists), in text mode using Unicode encoding.
// It then writes two strings into the file
// and then closes the file.
 
#include <stdio.h>
#include <stddef.h>
#include <stdlib.h>
#include <wchar.h>

#define BUFFER_SIZE 50

int main(int argc, char** argv)
{
wchar_t str[BUFFER_SIZE];
size_t  strSize;
FILE*   fileHandle;

    // Create an the xml file in text and Unicode encoding mode.
    if ((fileHandle = _wfopen( L"_wfopen_test.xml",L"wt+,ccs=UNICODE")) == NULL) // C4996
    // Note: _wfopen is deprecated; consider using _wfopen_s instead
    {
        wprintf(L"_wfopen failed!\n");
        return(0);
    }

    // Write a string into the file.
    wcscpy_s(str, sizeof(str)/sizeof(wchar_t), L"<xmlTag>\n");
    strSize = wcslen(str);
    if (fwrite(str, sizeof(wchar_t), strSize, fileHandle) != strSize)
    {
        wprintf(L"fwrite failed!\n");
    }

    // Write a string into the file.
    wcscpy_s(str, sizeof(str)/sizeof(wchar_t), L"</xmlTag>");
    strSize = wcslen(str);
    if (fwrite(str, sizeof(wchar_t), strSize, fileHandle) != strSize)
    {
        wprintf(L"fwrite failed!\n");
    }

    // Close the file.
    if (fclose(fileHandle))
    {
        wprintf(L"fclose failed!\n");
    }
    return 0;
}

.NET Framework の相当するアイテム

• System::IO::File::Open

• System::IO::FileStream::FileStream

参照

参照

ストリーム入出力

マルチバイト文字のシーケンスの解釈

fclose、_fcloseall

_fdopen、_wfdopen

ferror

_fileno

freopen、_wfreopen

_open、_wopen

_setmode

_sopen、_wsopen