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 デスクトップ アプリケーションでは、SetFileApisToOEM関数を使用して OEM コード ページ (CP_OEMCP) に変更できます。 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 が表示されていない場合またはファイルが新しいファイルの場合にのみ使用されます。

Note

BOM 検出は、Unicode モードで (つまり、 ccs フラグを渡して) 開かれたファイルにのみ適用されます。

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

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

ccs フラグ	BOM なし (または新しいファイル)	BOM: UTF-8	BOM: UTF-16
UNICODE	UTF-16LE	UTF-8	UTF-16LE
UTF-8	UTF-8	UTF-8	UTF-16LE
UTF-16LE	UTF-16LE	UTF-8	UTF-16LE

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

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

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

TCHAR.H ルーチン	_UNICODE と _MBCS が定義されていない	_MBCS が定義されている	_UNICODE が定義されている
_tfopen	fopen	fopen	_wfopen

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

mode	アクセス
"r"	読み取り用に開きます。 ファイルが存在しないか、見つからない場合、 fopen 呼び出しは失敗します。
"w"	書き込み用に空のファイルを開きます。 指定したファイルが既に存在すると、そのファイルの内容は破棄されます。
"a"	末尾に書き込みができるようにファイルを開きます (追加モード)。EOF (end-of-file) マーカーを削除せずにファイルに新しいデータを書き込みます。 ファイルが存在しない場合は、作成します。
"r+"	読み取りと書き込みの両方のモードで開きます。 ファイルが存在する必要があります。
"w+"	読み取りと書き込みの両方のモードで空のファイルを開きます。 そのファイルが既に存在すると、そのファイルの内容は破棄されます。
"a+"	読み取りと追加の両方のモードでファイルを開きます。 追加操作には、新しいデータをファイルに書き込む前に EOF マーカーを削除することが含まれます。 書き込みの完了後に、EOF マーカーは復元されません。 ファイルが存在しない場合は、作成します。

アクセスの種類 "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 に次の文字を追加すると、改行文字の変換モードを指定できます。

mode modifier	変換モード
t	ファイルをテキスト (変換) モードで開きます。 復帰改行 (CR-LF) の組み合わせは入力時に単一ライン フィード (LF) に変換され、LF 文字は出力時に CR-LF の組み合わせに変換されます。 また、Ctrl + Z は入力時に EOF (end-of-file) 文字として解釈されます。
b	ファイルをバイナリ (無変換) モードで開きます。復帰文字と改行文字の変換は行われません。

テキスト モードでは、 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 modifier	Behavior
x	filenameが既に存在する場合は、関数を強制的に失敗します。 "w" または "w+" 指定子と組み合わせる場合にのみ使用できます。
c	関連付けられた filename のコミット フラグを有効にして、 fflush または _flushall のいずれかが呼び出された場合に、ファイル バッファーの内容がディスクに直接書き込まれるようにします。
n	関連付けられている filename のコミット フラグを "コミットなし" にリセットします。このフラグが既定値です。 プログラムを COMMODE.OBJ とリンクする場合は、グローバル コミット フラグもオーバーライドします。 プログラムを COMMODE に明示的にリンクしない限り、グローバル コミット フラグの既定値は "コミットなし" です。OBJ ( リンク オプションを参照)。
N	ファイルが子プロセスによって継承されないように指定します。
S	キャッシュがディスクからのシーケンシャル アクセスに最適化されるように指定します。ただし、シーケンシャル アクセスに限定されるわけではありません。
R	キャッシュがディスクからのランダム アクセスに最適化されるように指定します。ただし、ランダム アクセスに限定されるわけではありません。
T	メモリ不足が必要な場合を除き、ディスクに書き込まれないファイルを指定します。
D	最後のファイル ポインターが閉じられたときに削除される一時ファイルを指定します。
ccs=encoding	このファイルに使用するエンコードされた文字セット (UTF-8、UTF-16LE、UNICODE のいずれか) を指定します。 何も指定しない場合は、ANSI エンコーディングが使用されます。 このフラグは、その前にコンマ (,) を付けるフラグから区切られます。 例: FILE *f = fopen("newfile.txt", "rt+, ccs=UTF-8");

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

mode 文字列の文字	_open/_sopen に相当する oflag 値
a	_O_WRONLY | _O_APPEND (通常は _O_WRONLY | _O_CREAT | _O_APPEND)
a+	_O_RDWR | _O_APPEND (通常は _O_RDWR | _O_APPEND | _O_CREAT )
r	_O_RDONLY
r+	_O_RDWR
w	_O_WRONLY (通常は _O_WRONLY | _O_CREAT | _O_TRUNC)
w+	_O_RDWR (通常は _O_RDWR | _O_CREAT | _O_TRUNC)
b	_O_BINARY
t	_O_TEXT (翻訳済み)
x	_O_EXCL
c	なし
n	なし
S	_O_SEQUENTIAL
R	_O_RANDOM
T	_O_SHORTLIVED
D	_O_TEMPORARY
ccs=UNICODE	_O_WTEXT
*ccs=UTF-8*	_O_UTF8
ccs=UTF-16LE	_O_UTF16

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

TとDについて:

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

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

要件

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

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

c、n、t、S、R、T、D modeのオプションは、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