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

pFile
開かれたファイルへのポインターを受け取るファイル ポインターへのポインター。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, and _sys_nerrFor more information about these error codes, see errno, _doserrno, _sys_errlist, and _sys_nerr.

エラー条件Error Conditions

pFile filename mode 戻り値Return Value の内容 pFileContents of pFile
NULL anyany anyany EINVAL 変更なしunchanged
anyany NULL anyany EINVAL 変更なしunchanged
anyany anyany NULL EINVAL 変更なしunchanged

解説Remarks

およびによって開かれたファイルは fopen_s _wfopen_s 共有できません。Files that are opened by fopen_s and _wfopen_s aren't 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_s****fopen_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 、または mode が 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 do 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, and _sys_nerr」を参照してください。For more information, see errno, _doserrno, _sys_errlist, and _sys_nerr.

既定では、この関数のグローバル状態はアプリケーションにスコープが設定されています。By default, this function's global state is scoped to the application. これを変更するには、「 CRT でのグローバル状態」を参照してください。To change this, see Global state in the CRT.

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_**");

エンコード に使用できる値は UNICODE 、、、 UTF-8 および UTF-16LE です。Allowed values of encoding are UNICODE, UTF-8, and UTF-16LE. に値が指定されていない場合 encoding 、は 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
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 が書き込まれます。Files that are opened for writing in Unicode mode have a BOM written to them automatically.

mode"a, 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 reopens the file with write-only access. (これはモードにのみ適用され、には適用さ a れません a+ )。(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 fopen_s fopen_s _wfopen_s

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

mode アクセスAccess
"r" 読み取り用に開きます。Opens for reading. ファイルが存在しない場合、または見つからない場合、 fopen_s 呼び出しは失敗します。If the file doesn't exist or cannot be found, the fopen_s call fails.
"w" 書き込み用に空のファイルを開きます。Opens an empty file for writing. 指定したファイルが既に存在すると、そのファイルの内容は破棄されます。If the given file exists, its contents are destroyed.
"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 doesn't exist.
"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+" 読み取りと追加の両方のモードでファイルを開きます。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 isn't restored after writing is completed. ファイルが存在しない場合は、作成します。Creates the file if it doesn't 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 rewind が、既存のデータを上書きできないように、書き込み操作が実行される前に常にファイルの末尾に戻されます。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 doesn't 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+" EOF マーカーで終了するストリームファイルに追加するには、モードが必要です CTRL+ZThe "a+" mode is required for appending to a stream file that is terminated with 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 come across an EOF marker. EOF マーカーがない場合は、ファイルポジショニング関数に介在する呼び出しを使用する必要があります。If there's no EOF marker, you must use an intervening call to a file-positioning function. ファイル配置関数は、、 fsetposfseek および rewind です。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.

C11 以降で "x" は、をまたはに追加し "w" て、ファイルが存在する場合は上書きせずに、関数を失敗させることができ "w+" ます。Starting in C11, you can append "x" to "w" or "w+" to cause the function fail if the file exists, instead of overwriting it.

上記の値に加え、に次の文字を追加して、 mode 改行文字の変換モードを指定できます。In addition to the values above, the following characters can be included in mode to specify the translation mode for newline characters:

mode 変換mode modifier 変換モードTranslation mode
t ファイルをテキスト (変換) モードで開きます。Open in text (translated) mode.
b バイナリ (無変換) モードで開く復帰文字と改行文字を含む翻訳は抑制されます。Open in binary (untranslated) mode; translations involving carriage-return and line feed 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. これは、とを使用して、 fseek ftell で終わるファイル内を移動すると CTRL+Zfseek ファイルの末尾付近でが正しく動作しなくなる可能性があるためです。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/line feed combinations are translated into single line feeds on input, and line feed characters are translated to carriage return-line feed 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 )。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 に指定されていない場合 mode 、既定の変換モードは _fmodeグローバル変数によって定義されます。If t or b isn't 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 変換mode modifier 動作Behavior
c またはが呼び出された場合に、ファイルバッファーの内容がディスクに直接書き込まれるように、関連付けられている ファイル名 のコミットフラグを有効にし 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.
n 関連付けられている ファイル名 のコミットフラグを "コミットなし" にリセットします。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).
n ファイルが子プロセスによって継承されないことを指定します。Specifies that the file isn't inherited by child processes.
S キャッシュがディスクからのシーケンシャル アクセスに最適化されるように指定します。ただし、シーケンシャル アクセスに限定されるわけではありません。Specifies that caching is optimized for, but not restricted to, sequential access from disk.
R キャッシュがディスクからのランダム アクセスに最適化されるように指定します。ただし、ランダム アクセスに限定されるわけではありません。Specifies that caching is optimized for, but not restricted to, random access from disk.
t ファイルを一時ファイルとして指定します。Specifies a file as temporary. 可能であれば、ディスクにフラッシュされません。If possible, it isn't flushed to disk.
D ファイルを一時ファイルとして指定します。Specifies a file as temporary. 最後のファイルポインターが閉じられると、削除されます。It's deleted when the last file pointer is closed.
ccs=暗号化ccs=encoding このファイルに使用するエンコードされた文字セット ( UTF-8 、、またはのいずれか) を指定し UTF-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.

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

文字列内の文字 modeCharacters in mode string oflag に相当する値_open/_sopenEquivalent oflag value for _open/_sopen
a _O_WRONLY | _O_APPEND (通常は _O_WRONLY | _O_CREAT | _O_APPEND )_O_WRONLY | _O_APPEND (usually _O_WRONLY | _O_CREAT | _O_APPEND)
a+ _O_RDWR | _O_APPEND (通常は _O_RDWR | _O_APPEND | _O_CREAT )_O_RDWR | _O_APPEND (usually _O_RDWR | _O_APPEND | _O_CREAT)
R _O_RDONLY
r+ _O_RDWR
w _O_WRONLY (通常は _O_WRONLY | _O_CREAT | _O_TRUNC)_O_WRONLY (usually _O_WRONLY | _O_CREAT | _O_TRUNC)
w+ _O_RDWR (通常は _O_RDWR | _O_CREAT | _O_TRUNC)_O_RDWR (usually _O_RDWR | _O_CREAT | _O_TRUNC)
b _O_BINARY
t _O_TEXT
c なしNone
n なしNone
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 ファイルが、コードを移植する必要がない場合や、ファイルの大部分を読み取ることが予想される場合、またはネットワークパフォーマンスが気にならない場合にもオプションとなることがあります。If you're using rb mode, memory mapped Win32 files might also be an option if you don't need to port your code, you expect to read much of the file, or you don't care about network performance.

必要条件Requirements

機能Function 必須ヘッダーRequired header
fopen_s <stdio.h>
_wfopen_s <stdio.h> または <wchar.h><stdio.h> or <wchar.h>

互換性について詳しくは、「 Compatibility」をご覧ください。For more compatibility information, see Compatibility.

ライブラリLibraries

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

cn 、およびオプションは、 t mode およびの Microsoft 拡張機能であり、 fopen_s ANSI の _fdopen 移植性が必要な場所では使用しないでください。The c, n, and t mode options are Microsoft extensions for fopen_s and _fdopen and shouldn't be used where you want ANSI portability.

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

関連項目See also

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