You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A pointer to the file pointer that will receive the pointer to the opened file.
34
+
A pointer to the file pointer that receives the pointer to the opened file.
35
35
36
36
*`filename`*\
37
-
Filename.
37
+
The name of the file to open.
38
38
39
39
*`mode`*\
40
40
Type of access permitted.
@@ -55,7 +55,7 @@ Zero if successful; an error code on failure. For more information about these e
55
55
56
56
The **`fopen_s`** and **`_wfopen_s`** functions can't open a file for sharing. If you need to share the file, use [`_fsopen` or `_wfsopen`](fsopen-wfsopen.md) with the appropriate sharing mode constant—for example, use `_SH_DENYNO` for read/write sharing.
57
57
58
-
The **`fopen_s`** function opens the file that's 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.
58
+
The **`fopen_s`** function opens the file specified by *`filename`*. **`_wfopen_s`** is a wide-character version of **`fopen_s`** and the arguments to **`_wfopen_s`** are wide-character strings. **`_wfopen_s`** and **`fopen_s`** behave identically, otherwise.
59
59
60
60
**`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. 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.
61
61
@@ -111,14 +111,14 @@ When the **`"r+"`**, **`"w+"`**, or **`"a+"`** access type is specified, both re
111
111
112
112
Starting in C11, you can append **`"x"`** to **`"w"`** or **`"w+"`** to cause the function fail if the file exists, instead of overwriting it.
113
113
114
-
In addition to the values above, the following characters can be included in *`mode`* to specify the translation mode for newline characters:
114
+
In addition to the previous values, the following characters can be included in *`mode`* to specify the translation mode for newline characters:
115
115
116
116
|*`mode`* modifier | Translation mode |
117
117
|--|--|
118
-
|**`t`**| Open in text (translated) mode. |
118
+
|**`t`**| Open in text (translated) mode. Carriage return-line feed (CR-LF) combinations are translated into single line feeds (LF) 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. |
119
119
|**`b`**| Open in binary (untranslated) mode; translations involving carriage-return and line feed characters are suppressed. |
120
120
121
-
In text (translated) 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. It's removed because using [`fseek`](fseek-fseeki64.md) and [`ftell`](ftell-ftelli64.md) to move within a file that ends with a `CTRL`+**Z**, may cause **`fseek`** to behave improperly near the end of the file.
121
+
In text (translated) mode, `CTRL`+**Z** is interpreted as an end-of-file character on input. For 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. It's removed because using [`fseek`](fseek-fseeki64.md) and [`ftell`](ftell-ftelli64.md) to move within a file that ends with a `CTRL`+**Z**, may cause **`fseek`** to behave improperly near the end of the file.
122
122
123
123
Also, in text mode, carriage return/line feed (CRLF) combinations are translated into single line feed (LF) characters on input, and LF characters are translated to CRLF 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. 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).
124
124
@@ -133,8 +133,8 @@ For more information about using text and binary modes in Unicode and multibyte
133
133
|**`N`**| Specifies that the file isn't inherited by child processes. |
134
134
|**`S`**| Specifies that caching is optimized for, but not restricted to, sequential access from disk. |
135
135
|**`R`**| Specifies that caching is optimized for, but not restricted to, random access from disk. |
136
-
|**`t`**| Specifies a file as temporary. If possible, it isn't flushed to disk. |
137
-
|**`D`**| Specifies a file as temporary. It's deleted when the last file pointer is closed. |
136
+
|**`T`**| Specifies a file that isn't written to disk unless memory pressure requires it. |
137
+
|**`D`**| Specifies a temporary file that is deleted when the last file pointer to it is closed. |
138
138
|**`ccs=UNICODE`**| Specifies UNICODE as the encoded character set to use for this file. Leave unspecified if you want ANSI encoding. |
139
139
|**`ccs=UTF-8`**| Specifies UTF-8 as the encoded character set to use for this file. Leave unspecified if you want ANSI encoding. |
140
140
|**`ccs=UTF-16LE`**| Specifies UTF-16LE as the encoded character set to use for this file. Leave unspecified if you want ANSI encoding. |
@@ -150,21 +150,26 @@ Valid characters for the *`mode`* string used in **`fopen_s`** and [`_fdopen`](f
The **`c`**, **`n`**, and**`t`***`mode`* options are Microsoft extensions for **`fopen_s`** and [`_fdopen`](fdopen-wfdopen.md) and shouldn't be used where you want ANSI portability.
164
+
The **`c`**, **`n`**, **`R`**,**`S`**, **`t`**, **`T`**, and **`D`***`mode`* options are Microsoft extensions for `fopen_s` and `_wfopen_s` and shouldn't be used when you want ANSI portability.
165
165
166
166
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.
167
167
168
+
Regarding `T` and `D`:
169
+
-`T` avoids writing the file to disk as long as memory pressure doesn't require it. For more information, see `FILE_ATTRIBUTE_TEMPORARY` in [File attribute constants](/windows/win32/fileio/file-attribute-constants), and also this blog post [It's only temporary](https://learn.microsoft.com/archive/blogs/larryosterman/its-only-temporary).
170
+
-`D` specifies a regular file that is written to disk. The difference is that it's automatically deleted when it's closed.
@@ -42,9 +42,9 @@ For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`
42
42
43
43
## Remarks
44
44
45
-
The **`fopen`** function opens the file that is specified by *`filename`*. By default, a narrow *`filename`* string is interpreted using the ANSI codepage (`CP_ACP`). In Windows Desktop applications, it can be changed to the OEM codepage (`CP_OEMCP`) by using the [`SetFileApisToOEM`](/windows/win32/api/fileapi/nf-fileapi-setfileapistooem) function. You can use the [`AreFileApisANSI`](/windows/win32/api/fileapi/nf-fileapi-arefileapisansi) function to determine whether *`filename`* is interpreted using the ANSI or the system default OEM codepage. **`_wfopen`** is a wide-character version of **`fopen`**; the **`_wfopen`** arguments are wide-character strings. Otherwise, **`_wfopen`** and **`fopen`** behave identically. Just using **`_wfopen`** doesn't affect the coded character set that's used in the file stream.
45
+
The **`fopen`** function opens the file specified by *`filename`*. By default, a narrow *`filename`* string is interpreted using the ANSI codepage (`CP_ACP`). In Windows Desktop applications, it can be changed to the OEM codepage (`CP_OEMCP`) by using the [`SetFileApisToOEM`](/windows/win32/api/fileapi/nf-fileapi-setfileapistooem) function. You can use the [`AreFileApisANSI`](/windows/win32/api/fileapi/nf-fileapi-arefileapisansi) function to determine whether *`filename`* is interpreted using the ANSI or the system default OEM codepage. **`_wfopen`** is a wide-character version of **`fopen`**; the **`_wfopen`** arguments are wide-character strings. Otherwise, **`_wfopen`** and **`fopen`** behave identically. Just using **`_wfopen`** doesn't affect the coded character set that's used in the file stream.
46
46
47
-
**`fopen`** accepts paths that are valid on the file system at the point of execution; **`fopen`** accepts UNC paths and paths that involve mapped network drives as long as the system that executes the code has access to the share or mapped drive at the time of execution. When you construct paths for **`fopen`**, make sure that drives, paths, or network shares will be available in the execution environment. You can use either forward slashes (`/`) or backslashes (`\`) as the directory separators in a path.
47
+
**`fopen`** accepts paths that are valid on the file system at the point of execution; **`fopen`** accepts UNC paths and paths that involve mapped network drives as long as the system that executes the code has access to the share or mapped drive at the time of execution. When you construct paths for **`fopen`**, make sure that drives, paths, or network shares are available in the execution environment. You can use either forward slashes (`/`) or backslashes (`\`) as the directory separators in a path.
48
48
49
49
Always check the return value to see whether the pointer is NULL before you perform any other operations on the file. If an error occurs, the global variable `errno` is set, and may be used to obtain specific error information. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md).
50
50
@@ -60,7 +60,7 @@ Allowed values for **`ccs`** encoding are `UNICODE`, **`UTF-8`**, and **`UTF-16L
60
60
61
61
When a file is opened in Unicode mode, input functions translate the data that's read from the file into UTF-16 data stored as type **`wchar_t`**. Functions that write to a file opened in Unicode mode expect buffers that contain UTF-16 data stored as type **`wchar_t`**. If the file is encoded as UTF-8, then UTF-16 data is translated into UTF-8 when it's written. The file's UTF-8-encoded content is translated into UTF-16 when it's read. An attempt to read or write an odd number of bytes in Unicode mode causes a [parameter validation](../parameter-validation.md) error. To read or write data that's stored in your program as UTF-8, use a text or binary file mode instead of a Unicode mode. You're responsible for any required encoding translation.
62
62
63
-
If the file already exists and is opened for reading or appending, then any byte order mark (BOM) in the file determines the encoding. The BOM encoding takes precedence over the encoding that's specified by the **`ccs`** flag. The **`ccs`** encoding is only used when no BOM is present or the file is a new file.
63
+
If the file already exists and is opened for reading or appending, then any byte order mark (BOM) in the file determines the encoding. The BOM encoding takes precedence over the encoding specified by the **`ccs`** flag. The **`ccs`** encoding is only used when no BOM is present or the file is a new file.
64
64
65
65
> [!NOTE]
66
66
> BOM detection only applies to files that are opened in Unicode mode (that is, by passing the **`ccs`** flag).
@@ -77,7 +77,7 @@ The following table summarizes the modes that are used for various **`ccs`** fla
77
77
78
78
Files opened for writing in Unicode mode have a BOM written to them automatically.
79
79
80
-
If *`mode`* is **`a, ccs=encoding`** for some `encoding` value, **`fopen`** first tries to open the file by using both read and write access. If this action succeeds, the function reads the BOM to determine the encoding for the file. If it fails, the function uses the default encoding for the file. In either case, **`fopen`**will then reopen the file by using write-only access. (This behavior applies to **`"a"`** mode only, not to **`"a+"`** mode.)
80
+
If *`mode`* is **`a, ccs=encoding`** for some `encoding` value, **`fopen`** first tries to open the file by using both read and write access. If this action succeeds, the function reads the BOM to determine the encoding for the file. If it fails, the function uses the default encoding for the file. In either case, **`fopen`**reopens the file using write-only access. (This behavior applies to **`"a"`** mode only, not to **`"a+"`** mode.)
81
81
82
82
### Generic-text routine mappings
83
83
@@ -106,7 +106,7 @@ In addition to the earlier values, the following characters can be appended to *
106
106
107
107
|*`mode`* modifier | Translation mode |
108
108
|--|--|
109
-
|**`t`**| Open in text (translated) mode. |
109
+
|**`t`**| Open in text (translated) mode. Carriage return-line feed (CR-LF) combinations are translated into single line feeds (LF) on input and LF characters are translated to CR-LF combinations on output. Also, CTRL+Z is interpreted as an end-of-file character on input. |
110
110
|**`b`**| Open in binary (untranslated) mode; translations involving carriage-return and line feed characters are suppressed. |
111
111
112
112
In text mode, `CTRL`+**Z** is interpreted as an EOF character on input. In files that are opened for reading/writing by using **`"a+"`**, **`fopen`** checks for a `CTRL`+**Z** at the end of the file and removes it, if it's possible. It's removed because using [`fseek`](fseek-fseeki64.md) and **`ftell`** to move within a file that ends with `CTRL`+**Z** may cause [`fseek`](fseek-fseeki64.md) to behave incorrectly near the end of the file.
@@ -127,8 +127,8 @@ The following options can be appended to *`mode`* to specify more behaviors.
127
127
|**`N`**| Specifies that the file isn't inherited by child processes. |
128
128
|**`S`**| Specifies that caching is optimized for, but not restricted to, sequential access from disk. |
129
129
|**`R`**| Specifies that caching is optimized for, but not restricted to, random access from disk. |
130
-
|**`T`**| Specifies a file as temporary. If possible, it isn't flushed to disk. |
131
-
|**`D`**| Specifies a file as temporary. It's deleted when the last file pointer is closed. |
130
+
|**`T`**| Specifies a file that isn't written to disk unless memory pressure requires it. |
131
+
|**`D`**| Specifies a temporary file that's deleted when the last file pointer to it is closed. |
132
132
|**`ccs=encoding`**| Specifies the encoded character set to use (one of **`UTF-8`**, **`UTF-16LE`**, or `UNICODE`) for this file. Leave unspecified if you want ANSI encoding. This flag is separated from flags that precede it by a comma (`,`). For example: `FILE *f = fopen("newfile.txt", "rt+, ccs=UTF-8");`|
133
133
134
134
Valid characters for the *`mode`* string that is used in **`fopen`** and **`_fdopen`** correspond to *`oflag`* arguments that are used in [`_open`](open-wopen.md) and [`_sopen`](sopen-wsopen.md), as follows.
@@ -142,7 +142,7 @@ Valid characters for the *`mode`* string that is used in **`fopen`** and **`_fdo
@@ -156,6 +156,13 @@ Valid characters for the *`mode`* string that is used in **`fopen`** and **`_fdo
156
156
157
157
If you're using **`rb`** mode, you don't have to port your code, and if you expect to read most of a large file or aren't concerned about network performance, you might also consider whether to use memory mapped Win32 files as an option.
158
158
159
+
Regarding `T` and `D`:
160
+
-`T` avoids writing the file to disk as long as memory pressure doesn't require it. For more information, see `FILE_ATTRIBUTE_TEMPORARY` in [File attribute constants](/windows/win32/fileio/file-attribute-constants), and also this blog post [It's only temporary](https://learn.microsoft.com/archive/blogs/larryosterman/its-only-temporary).
161
+
-`D` specifies a regular file that is written to disk. The difference is that it's automatically deleted when it's closed.
162
+
You can combine `TD` to get both semantics.
163
+
164
+
The **`c`**, **`n`**, **`R`**, **`S`**, **`t`**, **`T`**, and **`D`***`mode`* options are Microsoft extensions for `fopen` and `_wfopen` and shouldn't be used when you want ANSI portability.
![learn-build-service-prod[bot]](https://avatars.githubusercontent.com/in/237442?v=4&size=40){kind=avatar}
0 commit comments