diff options
Diffstat (limited to 'devdocs/c/io%2Ffopen.html')
| -rw-r--r-- | devdocs/c/io%2Ffopen.html | 89 |
1 files changed, 89 insertions, 0 deletions
diff --git a/devdocs/c/io%2Ffopen.html b/devdocs/c/io%2Ffopen.html new file mode 100644 index 00000000..802ab3fc --- /dev/null +++ b/devdocs/c/io%2Ffopen.html @@ -0,0 +1,89 @@ + <h1 id="firstHeading" class="firstHeading">fopen, fopen_s</h1> <table class="t-dcl-begin"> <tr class="t-dsc-header"> <th> Defined in header <code><stdio.h></code> </th> <th> </th> <th> </th> </tr> <tr class="t-dcl-rev-aux"> <td></td> <td rowspan="3">(1)</td> <td></td> </tr> <tr class="t-dcl t-until-c99"> <td> <pre data-language="c">FILE *fopen( const char *filename, const char *mode );</pre> +</td> <td> <span class="t-mark-rev t-until-c99">(until C99)</span> </td> </tr> <tr class="t-dcl t-since-c99"> <td> <pre data-language="c">FILE *fopen( const char *restrict filename, const char *restrict mode );</pre> +</td> <td> <span class="t-mark-rev t-since-c99">(since C99)</span> </td> </tr> <tr class="t-dcl t-since-c11"> <td> <pre data-language="c">errno_t fopen_s( FILE *restrict *restrict streamptr, + const char *restrict filename, + const char *restrict mode );</pre> +</td> <td> (2) </td> <td> <span class="t-mark-rev t-since-c11">(since C11)</span> </td> </tr> </table> <div class="t-li1"> +<span class="t-li">1)</span> Opens a file indicated by <code>filename</code> and returns a pointer to the file stream associated with that file. <code>mode</code> is used to determine the file access mode. </div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that the pointer to the file stream is written to <code>streamptr</code> and the following errors are detected at runtime and call the currently installed <a href="../error/set_constraint_handler_s" title="c/error/set constraint handler s">constraint handler</a> function: <ul> +<li> <code>streamptr</code> is a null pointer </li> +<li> <code>filename</code> is a null pointer </li> +<li> <code>mode</code> is a null pointer </li> +</ul> As with all bounds-checked functions, <code>fopen_s</code> only guaranteed to be available if <code>__STDC_LIB_EXT1__</code> is defined by the implementation and if the user defines <code>__STDC_WANT_LIB_EXT1__</code> to the integer constant <code>1</code> before including <a href="../io" title="c/io"><code><stdio.h></code></a>.</div> <h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> filename </td> <td> - </td> <td> file name to associate the file stream to </td> +</tr> <tr class="t-par"> <td> mode </td> <td> - </td> <td> null-terminated character string determining <a href="#File_access_flags">file access mode</a> </td> +</tr> <tr class="t-par"> <td> streamptr </td> <td> - </td> <td> pointer to a pointer where the function stores the result (an out-parameter) </td> +</tr> +</table> <h3 id="File_access_flags"> File access flags</h3> <table class="wikitable"> <tr> <th> File access <br>mode string </th> <th> Meaning </th> <th> Explanation </th> <th> Action if file <br> already exists </th> <th> Action if file <br> does not exist </th> +</tr> <tr> <td> <code>"r"</code> </td> <td> read </td> <td> Open a file for reading </td> <td> read from start </td> <td> failure to open </td> +</tr> <tr> <td> <code>"w"</code> </td> <td> write </td> <td> Create a file for writing </td> <td> destroy contents </td> <td> create new </td> +</tr> <tr> <td> <code>"a"</code> </td> <td> append </td> <td> Append to a file </td> <td> write to end </td> <td> create new </td> +</tr> <tr> <td> <code>"r+"</code> </td> <td> read extended </td> <td> Open a file for read/write </td> <td> read from start </td> <td> error </td> +</tr> <tr> <td> <code>"w+"</code> </td> <td> write extended </td> <td> Create a file for read/write </td> <td> destroy contents </td> <td> create new </td> +</tr> <tr> <td> <code>"a+"</code> </td> <td> append extended </td> <td> Open a file for read/write </td> <td> write to end </td> <td> create new </td> +</tr> <tr> <td colspan="5"> File access mode flag <code>"b"</code> can optionally be specified to open a file in binary mode. This flag has no effect on POSIX systems, but on Windows it disables special handling of <code>'\n'</code> and <code>'\x1A'</code>. <br> On the append file access modes, data is written to the end of the file regardless of the current position of the file position indicator. </td> +</tr> <tr> <td colspan="5"> The behavior is undefined if the mode is not one of the strings listed above. Some implementations define additional supported modes (e.g. <a rel="nofollow" class="external text" href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/fopen-wfopen">Windows</a>). </td> +</tr> <tr> <td colspan="5"> In update mode (<code>'+'</code>), both input and output may be performed, but output cannot be followed by input without an intervening call to <code><a href="fflush" title="c/io/fflush">fflush</a></code>, <code><a href="fseek" title="c/io/fseek">fseek</a></code>, <code><a href="fsetpos" title="c/io/fsetpos">fsetpos</a></code> or <code><a href="rewind" title="c/io/rewind">rewind</a></code>, and input cannot be followed by output without an intervening call to <code><a href="fseek" title="c/io/fseek">fseek</a></code>, <code><a href="fsetpos" title="c/io/fsetpos">fsetpos</a></code> or <code><a href="rewind" title="c/io/rewind">rewind</a></code>, unless the input operation encountered end of file. In update mode, implementations are permitted to use binary mode even when text mode is specified. </td> +</tr> <tr> <td colspan="5"> File access mode flag <code>"x"</code> can optionally be appended to <code>"w"</code> or <code>"w+"</code> specifiers. This flag forces the function to fail if the file exists, instead of overwriting it. <span class="t-mark-rev t-since-c11">(C11)</span> </td> +</tr> <tr> <td colspan="5"> When using <code>fopen_s</code> or <code>freopen_s</code>, file access permissions for any file created with <code>"w"</code> or <code>"a"</code> prevents other users from accessing it. File access mode flag <code>"u"</code> can optionally be prepended to any specifier that begins with <code>"w"</code> or <code>"a"</code>, to enable the default <code>fopen</code> permissions. <span class="t-mark-rev t-since-c11">(C11)</span> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <div class="t-li1"> +<span class="t-li">1)</span> If successful, returns a pointer to the new file stream. The stream is fully buffered unless <code>filename</code> refers to an interactive device. On error, returns a null pointer. <a rel="nofollow" class="external text" href="https://pubs.opengroup.org/onlinepubs/9699919799/functions/fopen.html">POSIX requires</a> that <code><a href="../error/errno" title="c/error/errno">errno</a></code> be set in this case.</div> <div class="t-li1"> +<span class="t-li">2)</span> If successful, returns zero and a pointer to the new file stream is written to <code>*streamptr</code>. On error, returns a non-zero error code and writes the null pointer to <code>*streamptr</code> (unless <code>streamptr</code> is a null pointer itself).</div> <h3 id="Notes"> Notes</h3> <p>The format of <code>filename</code> is implementation-defined, and does not necessarily refer to a file (e.g. it may be the console or another device accessible though filesystem API). On platforms that support them, <code>filename</code> may include absolute or relative filesystem path.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> <div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + const char* fname = "/tmp/unique_name.txt"; // or tmpnam(NULL); + int is_ok = EXIT_FAILURE; + + FILE* fp = fopen(fname, "w+"); + if (!fp) { + perror("File opening failed"); + return is_ok; + } + fputs("Hello, world!\n", fp); + rewind(fp); + + int c; // note: int, not char, required to handle EOF + while ((c = fgetc(fp)) != EOF) // standard C I/O file reading loop + putchar(c); + + if (ferror(fp)) + puts("I/O error when reading"); + else if (feof(fp)) { + puts("End of file is reached successfully"); + is_ok = EXIT_SUCCESS; + } + + fclose(fp); + remove(fname); + return is_ok; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">Hello, world! +End of file is reached successfully</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.21.5.3 The fopen function (p: 223-224) </li> +<li> K.3.5.2.1 The fopen_s function (p: 428-429) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.21.5.3 The fopen function (p: 305-306) </li> +<li> K.3.5.2.1 The fopen_s function (p: 588-590) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.5.3 The fopen function (p: 271-272) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.5.3 The fopen function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fclose" title="c/io/fclose"> <span class="t-lines"><span>fclose</span></span></a></div> </td> <td> closes a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fflush" title="c/io/fflush"> <span class="t-lines"><span>fflush</span></span></a></div> </td> <td> synchronizes an output stream with the actual file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="freopen" title="c/io/freopen"> <span class="t-lines"><span>freopen</span><span>freopen_s</span></span></a></div> +<div><span class="t-lines"><span><span class="t-mark-rev t-since-c11">(C11)</span></span></span></div> </td> <td> open an existing stream with a different name <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/fopen" title="cpp/io/c/fopen">C++ documentation</a></span> for <code>fopen</code> </td> +</tr> </table> <div class="_attribution"> + <p class="_attribution-p"> + © cppreference.com<br>Licensed under the Creative Commons Attribution-ShareAlike Unported License v3.0.<br> + <a href="https://en.cppreference.com/w/c/io/fopen" class="_attribution-link">https://en.cppreference.com/w/c/io/fopen</a> + </p> +</div> |