fopen_s, _wfopen_s

ファイルを開きます。 のこれらのバージョンには、「fopen_wfopenCRT のセキュリティ機能」の説明に従って、セキュリティが強化されています。

構文

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 any any EINVAL 変更なし
any NULL any EINVAL 変更なし
any any NULL EINVAL 変更なし

解説

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

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

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

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

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

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

Unicode のサポート

fopen_s は Unicode のファイル ストリームをサポートします。 新規または既存の Unicode ファイルを開くには、目的のエンコードを指定するフラグを にfopen_sccsします。次に例を示します。

fopen_s(&fp, "newfile.txt", "w+, ccs=UNICODE");

フラグの ccs 使用できる値は、 UNICODEUTF-8、および です UTF-16LE。 にccsfopen_s値が指定されていない場合は、ANSI エンコードが使用されます。

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

Note

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

次の表は、ファイル内の BOM に対してfopen_s与えられるさまざまなccsフラグ値のモードをまとめたものです。

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

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

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

が 、、"a, ccs=UTF-8"または "a, ccs=UTF-16LE"fopen_s場合mode"a, ccs=UNICODE"、最初に読み取りアクセスと書き込みアクセスの両方でファイルを開こうとします。 成功すると、この関数は BOM を読み取ってファイルのエンコーディングを決定します。失敗した場合は、ファイルに対して既定のエンコーディングを使用します。 どちらの場合も、fopen_s は、書き込み専用アクセスでファイルを開き直します。 (この動作はモードにのみ適用され、モードには適用aされません)。a+

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

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

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

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

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

C11 以降では、"w" または "w+""x" を付加すると、ファイルが存在する場合に上書きするのではなく、関数を失敗させることができます。

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

mode modifier 変換モード
t ファイルをテキスト (変換) モードで開きます。
b ファイルをバイナリ (無変換) モードで開きます。復帰文字と改行文字の変換は行われません。

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

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

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

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

mode modifier 動作
c 関連付けられた filename のコミット フラグを有効にして、 fflush または _flushall のいずれかが呼び出された場合に、ファイル バッファーの内容がディスクに直接書き込まれるようにします。
n "コミットなし" に関連付けられている filename のコミット フラグをリセットします。このフラグが既定です。 また、プログラム COMMODE.OBJを にリンクすると、グローバル コミット フラグもオーバーライドされます。 プログラム COMMODE.OBJ を明示的にリンクしない限り、グローバル コミット フラグの既定値は "コミットなし" です (「 リンク オプション」を参照)。
N ファイルが子プロセスによって継承されないように指定します。
S キャッシュがディスクからのシーケンシャル アクセスに最適化されるように指定します。ただし、シーケンシャル アクセスに限定されるわけではありません。
R キャッシュがディスクからのランダム アクセスに最適化されるように指定します。ただし、ランダム アクセスに限定されるわけではありません。
t ファイルを一時ファイルとして指定します。 可能な場合、ファイルはディスクにフラッシュされません。
D ファイルを一時ファイルとして指定します。 最後のファイル ポインターが閉じられると、ファイルは削除されます。
ccs=UNICODE このファイルに使用するエンコード文字セットとして UNICODE を指定します。 何も指定しない場合は、ANSI エンコーディングが使用されます。
ccs=UTF-8 このファイルに使用するエンコード文字セットとして UTF-8 を指定します。 何も指定しない場合は、ANSI エンコーディングが使用されます。
ccs=UTF-16LE このファイルに使用するエンコード文字セットとして UTF-16LE を指定します。 何も指定しない場合は、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

cn、および tmode オプションは、fopen_s および _fdopen の Microsoft 拡張機能です。ANSI の移植性が必要な場合は使用しないでください。

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

必要条件

機能 必須ヘッダー C++ ヘッダー
fopen_s <stdio.h> <cstdio>
_wfopen_s <stdio.h> または <wchar.h> <cstdio>

C ランタイム ライブラリの標準準拠と名前付け規則の詳細については、「 互換性」を参照してください。

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

<tchar.h> ルーチン _UNICODE_MBCS が定義されていない _MBCS が定義されている _UNICODE が定義されている
_tfopen_s fopen_s fopen_s _wfopen_s

ライブラリ

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

// 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" doesn't 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+, ccs=UTF-8" );
   if( err == 0 )
   {
      printf( "The file 'data2' was opened\n" );
   }
   else
   {
      printf( "The file 'data2' was not opened\n" );
   }

   // Close stream if it isn't 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 );
}
The file 'crt_fopen_s.c' was opened
The file 'data2' was opened
Number of files closed by _fcloseall: 1

関連項目

ストリーム入出力
fclose, _fcloseall
_fdopen, _wfdopen
ferror
_fileno
freopen, _wfreopen
_open, _wopen
_setmode