fopen, fopen

Opens a file with the specified open mode.

#include <stdio.h>

FILE *fopen(const char *filename, const char *mode);
errno_t fopen_s(FILE **pStream, const char *filename, const char *mode);

#include <wchar.h>

FILE *_wfopen(const wchar_t *filename, const wchar_t * mode);
errno_t _wfopen_s(FILE** pStream, const wchar_t *filename, const wchar_t *mode);

Parameters

filename: Pathname of file.
mode: Specifies the open mode (type of access permitted) for the file.
pStream: A pointer to the stream pointer that will receive the pointer to the opened file.

Remarks

This list gives the possible values of the mode parameter, including required quotes. It also relates the mode string and the corresponding oflag arguments used in sopen.

Value	Description
"r"	Opens for reading. If the file does not exist or cannot be found, the call will fail. Relates to O_RDONLY.
"w"	Opens an empty file for writing. If the given file exists, its contents are destroyed. Relates to O_WRONLY (usually O_WRONLY \| O_CREAT \| O_TRUNC).
"a"	Opens for writing at the end of the file (appending); creates the file first if it doesn't exist. Relates to O_WRONLY \| O_APPEND (usually O_WRONLY \| O_CREAT \| O_APPEND).
"r+"	Opens for both reading and writing. The file must exist. Relates to O_RDWR.
"w+"	Opens an empty file for both reading and writing. If the given file exists, its contents are destroyed. Relates to O_RDWR (usually O_RDWR \| O_CREAT \| O_TRUNC).
"a+"	Opens for reading and appending; creates the file first if it doesn't exist. Relates to O_RDWR \| O_APPEND (usually O_RDWR \| O_APPEND \| O_CREAT).
"x"	Fails to open for writing if the file exists. Corresponds to open modes (O_WRONLY \| O_CREAT \| O_TRUNC \| O_EXCL)

Use the "w" and "w+" types with care, as they can destroy existing files.

An optional "x" following "w" or "w+" causes the fopen() call to fail if the file already exists.

When a file is opened with the "a" or "a+" open mode, all write operations occur at the end of the file, even if you've repositioned the file pointer using fseek or rewind. Thus, existing data cannot be overwritten.

When the "r+", "w+", or "a+" open mode is specified, both reading and writing are allowed (the file is open for update). However, when you switch between reading and writing, there must be an intervening rewind operation or fsetpos or fseek, which can reposition the file pointer, if desired.

In addition to these values, one of these characters can be included after mode but between the quotation marks to specify the translation mode for <LF> characters. The t and b characters correspond to the constants used in open and sopen, as listed below.

Value	Description
t	Open in text (translated) mode. <CR><LF> combinations are translated into single <LF> characters on input and <LF> characters are translated to <CR><LF> combinations on output. <Ctrl-Z> is interpreted as an end-of-file character on input. In files opened for reading or for reading/writing, checks for and removes <Ctrl-Z> if possible, because <Ctrl-Z> may cause fseek to behave improperly near the end of the file. Relates to O_TEXT.
b	Open in binary (untranslated) mode; the above translations are suppressed. Relates to O_BINARY.
c	Set commit mode so that the contents of a file buffer are flushed to disk if fflush or fclose is called, or if fflush is called implicitly as the result of writing a file stream.
ccs=UNICODE	Sets stream orientation to UNICODE. Relates to O_WTEXT.

fopen_s and _wfopen_s are the secure versions of the calls. All parameters are validated for these calls.

Streams are opened by default with no orientation. The oreintation is set on the first operation on the stream. For example if the first operation is a single-byte read or write then the stream becomes a byte-oriented stream. If the first operation is a wide-character read or write then the stream becomes a wide-oriented stream. Only a call to freopen or fwide can otherwise alter the orientation of a stream. A stream can be set to wide-orientation on opening by means of the non-standard ccs=UNICODE mode.

Return Values

fopen and _wfopen return a pointer to the open file on success, or NULL on failure.

fopen_s and _wfopen_s return 0 on success or an errno value on failure. A value of EINVAL is returned if any of the pStream, filename or mode parameters is NULL.

Generic Text Routines

`tchar.h` routine	`_UNICODE` not defined	`_UNICODE` defined
_tfopen	fopen	_wfopen
_tfopen_s	fopen_s	_wfopen_s

Requirements

Versions	Defined in	Include	Link to
INtime 3.0 INtime 6.0 (wide-characater and generic text versions)	intime/rt/include/stdio.h intime/rt/include/wchar.h intime/rt/include/tchar.h	stdio.h wchar.h tchar.h	clib.lib