fopen_s、_wfopen_sfopen_s, _wfopen_s

ファイルを開きます。Opens a file. これらのバージョンの fopen, _wfopen は、「CRT のセキュリティ機能」の説明にあるとおり、セキュリティが強化されたバージョンです。These versions of fopen, _wfopen have security enhancements, as described in Security Features in the CRT.

構文Syntax

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
);

パラメーターParameters

pFilepFile
開かれたファイルへのポインターを受け取るファイル ポインターへのポインター。A pointer to the file pointer that will receive the pointer to the opened file.

ファイル名filename
ファイル名。Filename.

モードmode
アクセス許可の種類。Type of access permitted.

戻り値Return Value

正常終了した場合は 0 を返します。失敗した場合はエラー コードを返します。Zero if successful; an error code on failure. これらのエラー コードの詳細については、「errno、_doserrno、_sys_errlist、および _sys_nerr」を参照してください。See errno, _doserrno, _sys_errlist, and _sys_nerr for more information about these error codes.

エラー条件Error Conditions

pFilepFile ファイル名filename モードmode 戻り値Return Value 内容pFileContents of pFile
NULLNULL 任意any 任意any EINVALEINVAL 変更なしunchanged
任意any NULLNULL 任意any EINVALEINVAL 変更なしunchanged
任意any 任意any NULLNULL EINVALEINVAL 変更なしunchanged

RemarksRemarks

によって開かれたファイルfopen_s_wfopen_sは共有できません。Files that are opened by fopen_s and _wfopen_s are not sharable. ファイルが共有されることを必要とする場合_fsopen、_wfsopenな適切な共有モード定数 — たとえば、 _SH_DENYNO読み取り/書き込み共有の。If you require that a file be sharable, use _fsopen, _wfsopen with the appropriate sharing mode constant—for example, _SH_DENYNO for read/write sharing.

Fopen_s関数で指定されているファイルが開きますfilenameします。The fopen_s function opens the file that's specified by filename. _wfopen_sのワイド文字バージョンは、 fopen_s; 引数 _wfopen_sはワイド文字列です。_wfopen_s is a wide-character version of fopen_s; the arguments to _wfopen_s are wide-character strings. _wfopen_sfopen_s動作は同じです。_wfopen_s and fopen_s behave identically otherwise.

fopen_sの実行時にファイル システムでは有効なパスを受け取りますUNC パスとをマップ済みネットワーク ドライブを含むパスでは受け入れfopen_s限り、コードを実行して、システムは、共有へのアクセスを持っているか、実行時にマップ済みネットワーク ドライブ。fopen_s accepts paths that are valid on the file system at the point of execution; UNC paths and paths that involve mapped network drives are accepted by fopen_s as long as the system that's executing the code has access to the share or mapped network drive at the time of execution. パスを構築する際にfopen_s、ドライブ、パス、可用性に関する前提条件を作成しない、または実行時環境のネットワークと共有します。When you construct paths for fopen_s, don't make assumptions about the availability of drives, paths, or network shares in the execution environment. ディレクトリのパス区切り記号としてスラッシュ (/) または円記号 (\) のどちらかを使用できます。You can use either forward slashes (/) or backslashes (\) as the directory separators in a path.

これらの関数では、パラメーターの検証が行われます。These functions validate their parameters. 場合pFilefilename、またはモードnull ポインターの場合は、」の説明に従って、これらの関数は、無効なパラメーター例外を生成パラメーターの検証.If pFile, filename, or mode is a null pointer, these functions generate an invalid parameter exception, as described in Parameter Validation.

ファイルでその他の操作を実行する前には、必ず戻り値をチェックして関数が成功したかどうかを確認します。Always check the return value to see if the function succeeded before you perform any further operations on the file. エラー コードが返されるエラーが発生する場合とグローバル変数errno設定されます。If an error occurs, the error code is returned and the global variable errno is set. 詳細については、「errno、_doserrno、_sys_errlist、_sys_nerr」をご覧ください。For more information, see errno, _doserrno, _sys_errlist, and _sys_nerr.

Unicode のサポートUnicode support

fopen_s Unicode のファイル ストリームをサポートしています。fopen_s supports Unicode file streams. 新規または既存の Unicode ファイルを開くには、渡す、 ccsに目的のエンコーディングを指定するフラグfopen_s:To open a new or existing Unicode file, pass a ccs flag that specifies the desired encoding to fopen_s:

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

値を許可エンコードUNICODEutf-8、およびUTF 16LEします。Allowed values of encoding are UNICODE, UTF-8, and UTF-16LE. ある値を指定しない場合のエンコードfopen_sは ANSI エンコーディングを使用します。If there no value is specified for encoding, fopen_s uses ANSI encoding.

既に存在するファイルを読み取り用または追加用に開く場合は、ファイル内にバイト順マーク (BOM: Byte Order Mark) があれば、それによってエンコーディングが決定されます。If the file already exists and is opened for reading or appending, the Byte Order Mark (BOM), if present in the file, determines the encoding. BOM エンコーディングよりも優先されるエンコードによって指定されるは、 ccsフラグ。The BOM encoding takes precedence over the encoding that's specified by the ccs flag. Ccs存在またはファイルが新しいファイルに BOM がない場合にのみ使用がエンコードされます。The ccs encoding is only used when no BOM is present or if the file is a new file.

注意

BOM 検出は、Unicode モードで開かれたファイルにのみ適用されます。つまりを渡して、 ccsフラグ。BOM-detection only applies to files that are opened in Unicode mode; that is, by passing the ccs flag.

次の表は、さまざまなモードを示しますccsフラグに指定されているfopen_sとファイルのバイト順序マークします。The following table summarizes the modes for various ccs flags that are given to fopen_s and for Byte Order Marks in the file.

ccs フラグおよび BOM に基づいて使用されるエンコーディングEncodings Used Based on ccs Flag and BOM

ccs フラグccs flag BOM なし (または新しいファイル)No BOM (or new file) BOM:UTF-8BOM: UTF-8 BOM:UTF-16BOM: UTF-16
UNICODEUNICODE UTF-16LEUTF-16LE UTF-8UTF-8 UTF-16LEUTF-16LE
UTF-8UTF-8 UTF-8UTF-8 UTF-8UTF-8 UTF-16LEUTF-16LE
UTF-16LEUTF-16LE UTF-16LEUTF-16LE UTF-8UTF-8 UTF-16LEUTF-16LE

Unicode モードで書き込むように開かれたファイルには、自動的に BOM が書き込まれます。Files that are opened for writing in Unicode mode have a BOM written to them automatically.

場合モード"、ccs =エンコード"fopen_s読み書きの両方で、ファイルを開くには、まずアクセスおよび書き込みアクセス。If mode is "a, ccs=encoding", fopen_s first tries to open the file with both read access and write access. 成功すると、この関数は BOM を読み取ってファイルのエンコーディングを決定します。失敗した場合は、ファイルに対して既定のエンコーディングを使用します。If successful, the function reads the BOM to determine the encoding for the file; if unsuccessful, the function uses the default encoding for the file. いずれの場合も、 fopen_s再書き込み専用アクセス権を持つファイルを開きます。In either case, fopen_s then re-opens the file with write-only access. (これに適用されます モードのみ、not +)。(This applies to a mode only, not a+.)

汎用テキスト ルーチンのマップGeneric-Text Routine Mappings

TCHAR.H のルーチンTCHAR.H routine _UNICODE および _MBCS が未定義の場合_UNICODE & _MBCS not defined _MBCS が定義されている場合_MBCS defined _UNICODE が定義されている場合_UNICODE defined
_tfopen_s_tfopen_s fopen_sfopen_s fopen_sfopen_s _wfopen_s_wfopen_s

文字の文字列モードファイルは、次のように要求するアクセスの種類を指定します。The character string mode specifies the kind of access that's requested for the file, as follows.

モードmode アクセスAccess
"r""r" 読み取り用に開きます。Opens for reading. ファイルが存在しないか見つからない場合、 fopen_s呼び出しは失敗します。If the file does not exist or cannot be found, the fopen_s call fails.
"w""w" 書き込み用に空のファイルを開きます。Opens an empty file for writing. 指定したファイルが既に存在すると、そのファイルの内容は破棄されます。If the given file exists, its contents are destroyed.
"a""a" 末尾に書き込みができるようにファイルを開きます (追加モード)。EOF (end-of-file) マーカーを削除せずにファイルに新しいデータを書き込みます。Opens for writing at the end of the file (appending) without removing the end-of-file (EOF) marker before new data is written to the file. ファイルが存在しない場合は、作成します。Creates the file if it does not exist.
"r+""r+" 読み取りと書き込みの両方のモードで開きます。Opens for both reading and writing. ファイルが存在している必要があります。The file must exist.
"w+""w+" 読み取りと書き込みの両方のモードで空のファイルを開きます。Opens an empty file for both reading and writing. そのファイルが既に存在すると、そのファイルの内容は破棄されます。If the file exists, its contents are destroyed.
"a+""a+" 読み取りと追加の両方のモードでファイルを開きます。Opens for reading and appending. 追加操作には、新しいデータをファイルに書き込む前に EOF マーカーを削除することが含まれます。The appending operation includes the removal of the EOF marker before new data is written to the file. 書き込みの完了後に、EOF マーカーは復元されません。The EOF marker is not restored after writing is completed. ファイルが存在しない場合は、作成します。Creates the file if it does not exist.

使用してファイルを開くと、 "a" または 「a +」 アクセスの種類、すべての書き込み操作、ファイルの末尾から行われます。When a file is opened by using the "a" or "a+" access type, all write operations occur at the end of the file. 使用して、ファイル ポインターの位置を変更できるfseekまたは巻き戻し、これは常に、ファイルの末尾に前に戻さ、書き込み操作が既存のデータを上書きすることはできません。The file pointer can be repositioned by using fseek or rewind, but it's always moved back to the end of the file before any write operation is carried out so that existing data cannot be overwritten.

"A" モードでは、ファイルを追加する前に EOF マーカーは削除されません。The "a" mode does not remove the EOF marker before appending to the file. 追加が行われても、MS-DOS TYPE コマンドでは元の EOF マーカーまでのデータしか表示されず、ファイルに追加されたデータは表示されません。After appending has occurred, the MS-DOS TYPE command only shows data up to the original EOF marker and not any data that's appended to the file. 「A +」 モードでファイルに追加する前に EOF マーカーは削除します。The "a+" mode does remove the EOF marker before appending to the file. 追加が終了すると、MS-DOS の TYPE コマンドでファイル内すべてのデータが表示されます。After appending, the MS-DOS TYPE command shows all data in the file. 「A +」 モードが CTRL + Z EOF マーカーを使用して終了するストリーム ファイルを追加するために必要です。The "a+" mode is required for appending to a stream file that is terminated by using the CTRL+Z EOF marker.

ときに、 「r +」「w +」、または 「a +」 アクセスの種類を指定すると、読み取りと書き込みの両方を許可します。When the "r+", "w+", or "a+" access type is specified, both reading and writing are allowed. (ファイルは "更新" モードで開きます)。ただし、読み取りから書き込みに切り替えると、入力操作は EOF マーカーを検出する必要があります。(The file is said to be open for "update".) However, when you switch from reading to writing, the input operation must encounter an EOF marker. EOF がない場合、ファイル ポジショニング関数の中間の呼び出しを使用する必要があります。If there is no EOF, you must use an intervening call to a file-positioning function. ファイル ポジショニング関数はfsetposfseek、および巻き戻しします。The file-positioning functions are fsetpos, fseek, and rewind. 書き込みから読み取りに切り替えたときに中間の呼び出しを使用する必要がありますfflushまたはファイル ポジショニング関数。When you switch from writing to reading, you must use an intervening call to either fflush or to a file-positioning function.

上記の値のほかに、次の文字を含めることがモード改行文字の変換モードを指定します。In addition to the above values, the following characters can be included in mode to specify the translation mode for newline characters:

モード修飾子mode modifier 変換モードTranslation mode
tt ファイルをテキスト (変換) モードで開きます。Open in text (translated) mode.
bb ファイルをバイナリ (無変換) モードで開きます。キャリッジ リターンとライン フィードの変換は行われません。Open in binary (untranslated) mode; translations involving carriage-return and linefeed characters are suppressed.

テキスト (変換) モードでは、CTRL + Z は入力ファイルの終端文字として解釈されます。In text (translated) mode, CTRL+Z is interpreted as an end-of-file character on input. ファイルを読み取り/書き込みで開いた 「a +」fopen_sファイルの末尾に CTRL + Z をチェックし、可能であれば削除します。In files opened for reading/writing with "a+", fopen_s checks for a CTRL+Z at the end of the file and removes it, if possible. これを使用して、 fseekftell CTRL + Z で終わるを引き起こす可能性のあるファイル内で移動するfseekファイルの末尾近くが正しく動作しません。This is done because using fseek and ftell to move within a file that ends with a CTRL+Z, may cause fseek to behave improperly near the end of the file.

また、テキスト モードで復帰と改行の組み合わせは、入力、1 つの改行に変換し、改行文字は出力に復帰と改行の組み合わせに変換します。Also, in text mode, carriage return-linefeed combinations are translated into single linefeeds on input, and linefeed characters are translated to carriage return-linefeed combinations on output. Unicode のストリーム入出力関数が既定のテキスト モードで動作すると、入力元または出力先のストリームはマルチバイト文字のシーケンスと仮定されます。When a Unicode stream-I/O function operates in text mode (the default), the source or destination stream is assumed to be a sequence of multibyte characters. このため、Unicode ストリーム入力関数はマルチバイト文字をワイド文字に変換し、 mbtowc 関数を呼び出した場合と同様の効果を得ます。Therefore, the Unicode stream-input functions convert multibyte characters to wide characters (as if by a call to the mbtowc function). 同様の理由で、Unicode ストリーム出力関数は、 wctomb 関数が呼び出されたかのように、ワイド文字をマルチバイト文字に変換します。For the same reason, the Unicode stream-output functions convert wide characters to multibyte characters (as if by a call to the wctomb function).

場合tまたはbには、指定しないモード、グローバル変数によって既定の変換モードが定義されている_fmodeします。If t or b is not given in mode, the default translation mode is defined by the global variable _fmode. 場合tまたはb先頭に、引数、関数が失敗して返しますNULLします。If t or b is prefixed to the argument, the function fails and returns NULL.

Unicode およびマルチバイトのストリーム入出力におけるテキスト モードおよびバイナリ モードの使い方の詳細については、「テキスト モードとバイナリ モードのファイル入出力」および「テキスト モードとバイナリ モードの Unicode ストリーム入出力」を参照してください。For more information about using text and binary modes in Unicode and multibyte stream-I/O, see Text and Binary Mode File I/O and Unicode Stream I/O in Text and Binary Modes.

モード修飾子mode modifier 動作Behavior
cc 関連付けられているコミット フラグを有効にするfilenameファイル バッファーの内容がいずれかのディスクに直接書き込まれるようにfflushまたは _flushallが呼び出されます。Enable the commit flag for the associated filename so that the contents of the file buffer are written directly to disk if either fflush or _flushall is called.
nn 関連付けられているコミット フラグをリセットfilename 「コミットなし」。Reset the commit flag for the associated filename to "no-commit." 既定値です。This is the default. プログラムを COMMODE.OBJ とリンクする場合は、グローバル コミット フラグもオーバーライドします。It also overrides the global commit flag if you link your program with COMMODE.OBJ. プログラムを明示的に COMMODE.OBJ とリンクしない場合、グローバル コミット フラグの既定の設定は "コミットなし" です (「 Link Options」をご覧ください)。The global commit flag default is "no-commit" unless you explicitly link your program with COMMODE.OBJ (see Link Options).
NN ファイルが子プロセスによって継承されないように指定します。Specifies that the file is not inherited by child processes.
SS キャッシュがディスクからのシーケンシャル アクセスに最適化されるように指定します。ただし、シーケンシャル アクセスに限定されるわけではありません。Specifies that caching is optimized for, but not restricted to, sequential access from disk.
RR キャッシュがディスクからのランダム アクセスに最適化されるように指定します。ただし、ランダム アクセスに限定されるわけではありません。Specifies that caching is optimized for, but not restricted to, random access from disk.
TT ファイルを一時ファイルとして指定します。Specifies a file as temporary. 可能な場合、ファイルはディスクにフラッシュされません。If possible, it is not flushed to disk.
DD ファイルを一時ファイルとして指定します。Specifies a file as temporary. 最後のファイル ポインターが閉じられると、ファイルは削除されます。It is deleted when the last file pointer is closed.
ccs=encodingccs=encoding 使用する設定でエンコードされた文字を指定します (いずれかのutf-8UTF 16LE、またはUNICODE) このファイル。Specifies the encoded character set to use (one of UTF-8, UTF-16LE, or UNICODE) for this file. 何も指定しない場合は、ANSI エンコーディングが使用されます。Leave unspecified if you want ANSI encoding.

有効な文字は、モードで使用される文字列fopen_s_fdopenに対応してoflagで使用される引数_開く_sopen、次のようにします。Valid characters for the mode string used in fopen_s and _fdopen correspond to oflag arguments used in _open and _sopen, as follows.

文字モード文字列Characters in mode string 等価oflag開く (_o)/_sopen の値Equivalent oflag value for _open/_sopen
aa _O_WRONLY | _O_APPEND (usually _O_WRONLY | _O_CREAT |** _O_APPEND**)_O_WRONLY | _O_APPEND (usually _O_WRONLY | _O_CREAT |** _O_APPEND**)
+a+ _O_RDWR | _O_APPEND (usually _O_RDWR | _O_APPEND | _O_CREAT )_O_RDWR | _O_APPEND (usually _O_RDWR | _O_APPEND | _O_CREAT )
rr _O_RDONLY_O_RDONLY
r+r+ _O_RDWR_O_RDWR
ww _O_WRONLY (usually _O_WRONLY | _O_CREAT |** _O_TRUNC**)_O_WRONLY (usually _O_WRONLY | _O_CREAT |** _O_TRUNC**)
w +w+ _O_RDWR (usually _O_RDWR | _O_CREAT | _O_TRUNC)_O_RDWR (usually _O_RDWR | _O_CREAT | _O_TRUNC)
bb _O_BINARY_O_BINARY
tt _O_TEXT_O_TEXT
cc なしNone
nn なしNone
SS _O_SEQUENTIAL_O_SEQUENTIAL
RR _O_RANDOM_O_RANDOM
TT _O_SHORTLIVED_O_SHORTLIVED
DD _O_TEMPORARY_O_TEMPORARY
ccs=UNICODEccs=UNICODE _O_WTEXT_O_WTEXT
ccs=UTF-8ccs=UTF-8 _O_UTF8_O_UTF8
ccs=UTF-16LEccs=UTF-16LE _O_UTF16_O_UTF16

使用する場合rbモードは、コードを移植して、大量のファイルを読み取る必要はありませんやネットワークのパフォーマンスは気にしない、Win32 メモリ マップト ファイルはオプションにもあります。If you are using rb mode, won't need to port your code, and expect to read a lot of the file and/or don't care about network performance, memory mapped Win32 files might also be an option.

必要条件Requirements

関数Function 必須ヘッダーRequired header
fopen_sfopen_s <stdio.h><stdio.h>
_wfopen_s_wfopen_s <stdio.h> または <wchar.h><stdio.h> or <wchar.h>

互換性の詳細については、「 互換性」を参照してください。For additional compatibility information, see Compatibility.

ライブラリLibraries

C ランタイム ライブラリのすべてのバージョン。All versions of the C run-time libraries.

Cn、およびt モードオプション用の Microsoft 拡張機能は、 fopen_s_fdopen ANSI 互換が必要な場合は使用する必要があります。The c, n, and t mode options are Microsoft extensions for fopen_s and _fdopen and should not be used where ANSI portability is desired.

Example

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

関連項目See also

ストリーム入出力Stream I/O
fclose、_fcloseallfclose, _fcloseall
_fdopen、_wfdopen_fdopen, _wfdopen
ferrorferror
_fileno_fileno
freopen、_wfreopenfreopen, _wfreopen
_open、_wopen_open, _wopen
_setmode_setmode