fopen、_wfopen

ファイルを開きます。 より多くのパラメーター検証を実行し、エラー コードを返す、より安全なバージョンのこれらの関数を使用できます。「 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 に設定します。

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

解説

fopen関数は、filenameで指定されたファイルを開きます。 既定では、狭い filename 文字列は ANSI コードページ (CP_ACP) を使用して解釈されます。 Windows デスクトップ アプリケーションでは、CP_OEMCP関数を使用して OEM コード ページ (SetFileApisToOEM) に変更できます。 AreFileApisANSI関数を使用して、が ANSI またはシステムの既定の OEM コード ページを使用して解釈されるかどうかを判断できます。 _wfopen は fopenのワイド文字バージョンです。 _wfopen 引数はワイド文字列です。 それ以外では、 _wfopen と fopen の動作は同じです。 _wfopenを使用するだけでは、ファイル ストリームで使用されるコード化された文字セットには影響しません。

fopen は、実行時にファイル システムで有効なパスを受け取ります。 fopen は、コードを実行するシステムが実行時に共有ネットワーク ドライブまたは割り当てられたネットワーク ドライブにアクセスする限り、UNC パスおよび割り当てられたネットワーク ドライブを含むパスを受け取ります。 fopenのパスを構築するときは、実行環境でドライブ、パス、またはネットワーク共有を使用できることを確認します。 パスのディレクトリ区切り記号として、スラッシュ (/) または円記号 (\) を使用できます。

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

既定では、この関数のグローバル状態の適用対象は、アプリケーションになります。 これを変更するには、「CRT でのグローバル状態」を参照してください。

Unicode のサポート

fopen は Unicode のファイル ストリームをサポートします。 Unicode ファイルを開くには、次のように、目的のエンコーディングを指定する ccs=encoding フラグを fopenに渡します。

FILE *fp = fopen("newfile.txt", "rt+, ccs=UTF-8");

ccs エンコードに使用できる値は、UNICODE、UTF-8、およびUTF-16LEです。

ファイルが Unicode モードで開かれると、Input 関数によって、ファイルから読み取られたデータは wchar_t型として格納された UTF-16 データに変換されます。 Unicode モードで開かれたファイルに書き込む関数は、 wchar_t型として格納された UTF-16 データがバッファーに含まれていると想定します。 ファイルが UTF-8 としてエンコードされている場合、UTF-16 データは書き込み時に UTF-8 に変換されます。 ファイルの UTF-8 でエンコードされたコンテンツは、読み取り時に UTF-16 に変換されます。 Unicode モードで奇数バイトの読み取りまたは書き込みを試みると、 パラメーター検証 エラーが発生します。 UTF-8 としてプログラムに格納されたデータを読み取るか書き込む場合は、Unicode モードではなくテキストまたはバイナリ ファイル モードを使用します。 必要なエンコード翻訳は、お客様の責任で行います。

ファイルが既に存在し、読み取りまたは追加のために開かれている場合は、ファイル内の任意のバイト オーダー マーク (BOM) によってエンコードが決定されます。 BOM エンコードは、 ccs フラグで指定されたエンコードよりも優先されます。 ccs エンコーディングは、BOM が表示されていない場合またはファイルが新しいファイルの場合にのみ使用されます。

ccs に指定される各種の fopen フラグとファイル内のバイト順マークに応じて、使用されるモードを次の表に示します。

ccs フラグと BOM に基づいて使用されるエンコード

Unicode モードで書き込むように開かれたファイルには、自動的に BOM が書き込まれます。

modeがa, ccs=encoding値に対してencodingされている場合、fopen最初に読み取りアクセスと書き込みアクセスの両方を使用してファイルを開こうとします。 このアクションが成功すると、関数は BOM を読み取ってファイルのエンコードを決定します。 失敗した場合、関数はファイルの既定のエンコードを使用します。 どちらの場合も、 fopen 書き込み専用アクセスを使用してファイルを再度開きます。 (この動作は "a" モードにのみ適用され、 "a+" モードには適用されません)。

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

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

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

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

"r+"、 "w+"、または "a+" のいずれかのアクセスの種類を指定すると、読み取りと書き込みの両方を行うことができます (ファイルは「更新」モードで開きます)。 ただし、読み取りから書き込みに切り替えると、入力操作は EOF マーカーを検出する必要があります。 EOF がない場合は、ファイル配置関数の中間呼び出しを使用する必要があります。 ファイル ポジショニング関数は、 fsetpos、 fseek、および rewindです。 書き込みから読み取りに切り替えると、 fflush またはファイル ポジショニング関数に中間の呼び出しを使用する必要があります。

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

テキスト モードでは、 CTRL+Z は入力時に EOF 文字として解釈されます。 "a+"を使用して読み取り/書き込み用に開かれたファイルでは、fopenファイルの末尾でCTRL+Zをチェックし、可能な場合は削除します。 fseekとftellを使用して、CTRL+Z で終わるファイル内を移動するとファイルの末尾付近でfseekが正しく動作しなくなる可能性があるため、削除されます。

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

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

Unicode およびマルチバイト ストリーム I/O でテキスト モードとバイナリ モードを使用する方法の詳細については、「Text およびバイナリ モード ファイル I/O およびテキスト モードとバイナリ モードでのUnicode ストリーム I/O を参照してください。

次のオプションを mode に追加して、より多くの動作を指定できます。

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

rb モードを使用している場合は、コードを移植する必要はありません。また、大きなファイルの大部分を読み取る必要がある場合や、ネットワーク パフォーマンスを心配しない場合は、メモリ マップされた Win32 ファイルをオプションとして使用するかどうかを検討することもできます。

TとDについて:

• T は、メモリ不足で必要ない限り、ファイルをディスクに書き込むのを回避します。 詳細については、FILE_ATTRIBUTE_TEMPORARYのと、このブログ投稿一時的なを参照してください。
• D は、ディスクに書き込まれる通常のファイルを指定します。 違いは、閉じられたときに自動的に削除されるということです。 TDを組み合わせて両方のセマンティクスを取得できます。

c、n、R、S、t、T、Dmodeのオプションは、fopenと_wfopen用の Microsoft 拡張機能であり、ANSI 移植性が必要な場合は使用しないでください。

要件

_wfopen は Microsoft 拡張機能です。 互換性の詳細については、「互換性」をご覧ください。

c、n、t、S、R、T、Dmodeのオプションは、fopenおよび_fdopen用の Microsoft 拡張機能であり、ANSI 移植性が必要な場合は使用しないでください。

例 1

次のプログラムは 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

例 2

次のプログラムでは、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;
}

関連項目

ストリーム入出力
マルチバイト文字のシーケンスの解釈
fclose, _fcloseall
_fdopen, _wfdopen
ferror
_fileno
freopen, _wfreopen
_open, _wopen
_setmode
_sopen, _wsopen