fopen_s、_wfopen_s

ファイルが開きます。fopen、_wfopen これらのバージョンのに CRT のセキュリティ機能に説明されているように、のセキュリティが強化があります。

errno_t fopen_s( 
   FILE** pFile,
   const char *filename,
   const char *mode 
);
errno_t _wfopen_s(
   FILE** pFile,
   const wchar_t *filename,
   const wchar_t *mode 
);

パラメーター

• [出力] pFile
  開かれたファイルへのポインターを受け取るファイル ポインターへのポインター。

• [入力] filename
  ファイル名。

• [入力] mode
  アクセス許可の種類。

戻り値

正常終了した場合は 0 を返します。失敗した場合はエラー コードを返します。これらのエラー コードに関する詳細については、errno、_doserrno、_sys_errlist、および _sys_nerr を参照してください。

エラー条件

pFile	filename	mode	戻り値	pFile の内容
NULL	任意	任意	EINVAL	変更なし
任意	NULL	任意	EINVAL	変更なし
任意	任意	NULL	EINVAL	変更なし

解説

fopen_s と _wfopen_s によって開かれたファイルは共有できません。ファイルを共有する必要がある場合には、定数例の適切な共有モードを使用 _fsopen、_wfsopen、読み取り/書き込み共有の _SH_DENYNO。

fopen_s 関数は filenameで指定されたファイルを開きます。_wfopen_s は fopen_s のワイド文字バージョンであり、_wfopen_s の引数はワイド文字列です。それ以外では、_wfopen_s と fopen_s の動作は同じです。

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

これらの関数では、パラメーターの検証が行われます。pFile、filename、または mode が null ポインターの場合、これらの関数は パラメーターの検証に説明されているように、無効なパラメーターの例外を生成します。

ファイルでそのほかの操作を実行する前に関数が成功したかどうかを必ず戻り値を確認します。エラーが発生すると、エラー コードが返され、グローバル変数 errno が設定されます。詳細については、「errno、_doserrno、_sys_errlist、および _sys_nerr」を参照してください。

Unicode のサポート

fopen_s のサポートの Unicode のファイル ストリーム。新規または既存の Unicode ファイルを開くには、fopen_sに目的のエンコーディングを指定する ccs のフラグを渡します。:

fopen_s(&fp, "newfile.txt", "rw, ccs=encoding");

encoding に指定できる値は、UNICODE、UTF-8、および UTF-16LE です。そこで値が encodingに指定していない場合は、fopen_s は、ANSI エンコーディングを使用します。

既に存在するファイルを読み取り用または追加用に開く場合は、ファイル内にバイト順マーク (BOM: Byte Order Mark) があれば、それによってエンコーディングが決定されます。BOM エンコーディングは ccs のフラグで指定されたエンコーディングよりも優先されます。ccs エンコーディングは、BOM が表示されていない場合またはファイルが新しいファイルの場合にのみ使用されます。

[!メモ]

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

次の表は fopen_s とファイル内のバイト順マークに対して指定する ccs の各種のフラグのモードの概要を示します。

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 が "a, ccs=<encoding>" の場合、fopen_s は、まず読み取りアクセス許可と書き込みアクセス許可の両方を持つファイルを開こうとします。成功すると、この関数は BOM を読み取ってファイルのエンコーディングを決定します。失敗した場合は、ファイルに対して既定のエンコーディングを使用します。いずれの場合も、fopen_s は、書き込み専用アクセスでファイルを開き直します。これは a モードにのみ適用され、a+ の場合は適用されません。

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

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

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

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

• "w"
  書き込み用に空のファイルを開きます。ファイルが存在する場合、の内容は破棄されます。

• "a"
  ファイルに新しいデータを書き込む前に EOF マーカーを削除せずにファイル (追加) の末尾に書き込み用に開きます。あるファイルを作成します。

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

• "w+"
  読み取りと書き込みの両方のモードで空のファイルを開きます。ファイルが存在する場合、の内容は破棄されます。

• "a+"
  読み取りと追加の開きます。追加操作を書き込むことが完了したら、新しいデータをファイルに書き込む EOF マーカーを復元する前に EOF マーカーが削除が含まれています。あるファイルを作成します。

ファイルが "a" または "a+" のアクセスの種類を使用して、開くと、すべての書き込み操作はファイルの末尾に発生します。ファイル ポインターは fseek か rewindを使用して位置を変更できますが、既存のデータが上書きできないように、書き込み操作の前にファイルの末尾まで常に実行されます。

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

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

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

• t
  ファイルをテキスト (変換) モードで開きます。このモードでは、Ctrl + Z は入力時に EOF (EOF: end-of-file) 文字として解釈されます。"a+" を使用して読み取りおよび書き込みの両方のモードで開かれたファイルでは、fopen_s がファイル末尾に 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 エンコーディングが使用されます。

fopen_s および _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
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 メモリ マップト ファイルも省略できます。

必要条件

Function	必須ヘッダー
fopen_s	<stdio.h>
_wfopen_s	<stdio.h> または <wchar.h>

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

ライブラリ

C ランタイム ライブラリのすべてのバージョン。

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

使用例

// crt_fopen_s.c
// 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 )
{
   errno_t err;

   // Open for read (will fail if file "crt_fopen_s.c" does not exist)
   err  = fopen_s( &stream, "crt_fopen_s.c", "r" );
   if( err == 0 )
   {
      printf( "The file 'crt_fopen_s.c' was opened\n" );
   }
   else
   {
      printf( "The file 'crt_fopen_s.c' was not opened\n" );
   }

   // Open for write 
   err = fopen_s( &stream2, "data2", "w+" );
   if( err == 0 )
   {
      printf( "The file 'data2' was opened\n" );
   }
   else
   {
      printf( "The file 'data2' was not opened\n" );
   }

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

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

同等の .NET Framework 関数

• System::IO::File::Open

• System::IO::FileStream::FileStream

参照

関連項目

ストリーム入出力

fclose、_fcloseall

_fdopen、_wfdopen

ferror

_fileno

freopen、_wfreopen

_open、_wopen

_setmode