fopen_s, _wfopen_s

Open a file. These are versions of fopen, _wfopen with security enhancements as described in Security Enhancements in the 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 
);

Parameters

• [out] pFile
  A pointer to the file pointer that will receive the pointer to the opened file.

• [in] filename
  Filename.

• [in] mode
  Type of access permitted.

Return Value

Zero if successful; an error code on failure. See _doserrno, errno, _sys_errlist, and _sys_nerr for more information on these, and other, error codes.

Error Conditions

pFile	filename	mode	Return Value	Contents ofpFile
NULL	any	any	EINVAL	unchanged
any	NULL	any	EINVAL	unchanged
any	any	NULL	EINVAL	unchanged

Remarks

Files opened by fopen_s and _wfopen_s are not sharable. 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).

The fopen_s function opens the file specified by filename. _wfopen_s is a wide-character version of fopen_s; the arguments to _wfopen_s are wide-character strings. _wfopen_s and fopen_s behave identically otherwise.

fopen_s will accept paths that are valid on the file system at the point of execution; UNC paths and paths involving mapped network drives are accepted by fopen_s as long as the system executing the code has access to the share or mapped network drive at the time of execution. Special care must be taken when constructing paths for fopen_s to avoid making assumptions about available drives, paths or network shares in the execution environment.

These functions validate their parameters. 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 performing any further operations on the file. If an error occurs, the error code is returned and the global variableerrno is set. For further information, see errno.

In Visual C++ 2005, fopen_s supports Unicode file streams. A flag specifying the desired encoding may be passed to fopen_s when opening a new file or overwriting an existing file, like this:

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

Allowed values of the encoding include UNICODE, UTF-8, and UTF-16LE. If the file is already in existence and is opened for reading or appending, the Byte Order Mark (BOM) is used to determine the correct encoding. It is not necessary to specify the encoding with a flag. In fact, the flag will be ignored if it conflicts with the type of the file as indicated by the BOM. The flag is only used when no BOM is present or if the file is a new file. The following table summarizes the modes used in for various flags given to fopen and Byte Order Marks used in the file.

Encodings Used Based on Flag and BOM

Flag	No BOM (or new file)	BOM: UTF-8	BOM: UTF-16
UNICODE	ANSI	UTF-8	UTF-16LE
UTF-8	UTF-8	UTF-8	UTF-16LE
UTF-16LE	UTF-16LE	UTF-8	UTF-16LE

If mode is "a, ccs=<encoding>", fopen_s will first try to open the file with both read and write access. If it succeeds, it will read the BOM to determine the encoding for this file; however, if it fails, it will use the default encoding for the file. In either case, fopen_s will then re-open the file with write-only access. (This applies to a mode only, not a+.)

Generic-Text Routine Mappings

TCHAR.H routine	_UNICODE & _MBCS not defined	_MBCS defined	_UNICODE defined
_tfopen_s	fopen_s	fopen_s	_wfopen_s

The character string mode specifies the type of access requested for the file, as follows:

• "r"
  Opens for reading. If the file does not 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"
  Opens for writing at the end of the file (appending) without removing the EOF marker before writing new data to the file; creates the file first if it doesn't exist.

• "r+"
  Opens for both reading and writing. (The file must exist.)

• "w+"
  Opens an empty file for both reading and writing. If the given file exists, its contents are destroyed.

• "a+"
  Opens for reading and appending; the appending operation includes the removal of the EOF marker before new data is written to the file and the EOF marker is restored after writing is complete; creates the file first if it doesn't exist.

When a file is opened with the "a" or "a+" access type, all write operations occur at the end of the file. The file pointer can be repositioned using fseek or rewind, but is always moved back to the end of the file before any write operation is carried out. Thus, existing data cannot be overwritten.

The "a" mode does not remove the EOF marker before appending to the file. After appending has occurred, the MS-DOS TYPE command only shows data up to the original EOF marker and not any data appended to the file. The "a+" mode does remove the EOF marker before appending to the file. After appending, the MS-DOS TYPE command shows all data in the file. The "a+" mode is required for appending to a stream file that is terminated with the CTRL+Z EOF marker.

When the "r+","w+", or "a+" access type is specified, both reading and writing are allowed (the file is said to be open for "update"). However, when you switch between reading and writing, there must be an intervening fflush, fsetpos, fseek, or rewind operation. The current position can be specified for the fsetpos or fseek operation, if desired.

In addition to the above values, the following characters can be included in mode to specify the translation mode for newline characters:

• t
  Open in text (translated) mode. In this mode, CTRL+Z is interpreted as an end-of-file character on input. 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. 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.

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. 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. Therefore, the Unicode stream-input functions convert multibyte characters to wide characters (as if by a call to the mbtowc function). For the same reason, the Unicode stream-output functions convert wide characters to multibyte characters (as if by a call to the wctomb function).

• b
  Open in binary (untranslated) mode; translations involving carriage-return and linefeed characters are suppressed.

If t or b is not given in mode, the default translation mode is defined by the global variable _fmode. If t or b is prefixed to the argument, the function fails and returns NULL.

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.

• c
  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. It also overrides the global commit flag if you link your program with COMMODE.OBJ. 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 is not 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 is not flushed to disk.

• D
  Specifies a file as temporary. It is deleted when the last file pointer is closed.

• ccs=ENCODING
  Specify the coded character set to use (ANSI, UTF-8, UTF-16LE, and UNICODE) for this file. This option is available in Visual C++ 2005 and later.

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	Equivalent oflag value for _open/_sopen
a	_O_WRONLY | _O_APPEND (usually _O_WRONLY | _O_CREAT |_O_APPEND)
a+	_O_RDWR | _O_APPEND (usually _O_RDWR | _O_APPEND | _O_CREAT )
r	_O_RDONLY
r+	_O_RDWR
w	_O_WRONLY (usually _O_WRONLY |_O_CREAT | _O_TRUNC)
w+	_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

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_s	<stdio.h>
_wfopen_s	<stdio.h> or <wchar.h>

For additional compatibility information, see Compatibility in the Introduction.

Libraries

All versions of the C run-time libraries.

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 )
{
   int numclosed;
   errno_t err;

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

   // Open for write 
   if( (err = fopen_s( &stream2, "data2", "w+" )) != 0 )
      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_s.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_s.c' was opened
The file 'data2' was opened
Number of files closed by _fcloseall: 1

.NET Framework Equivalent

• System::IO::File::Open

• System::IO::FileStream::FileStream

See Also

Concepts

Stream I/O

fclose, _fcloseall

_fdopen, _wfdopen

ferror

_fileno

freopen, _wfreopen

_open, _wopen

_setmode