diff options
Diffstat (limited to 'devdocs/c/io%2Ffreopen.html')
| -rw-r--r-- | devdocs/c/io%2Ffreopen.html | 82 |
1 files changed, 82 insertions, 0 deletions
diff --git a/devdocs/c/io%2Ffreopen.html b/devdocs/c/io%2Ffreopen.html new file mode 100644 index 00000000..74c69f8a --- /dev/null +++ b/devdocs/c/io%2Ffreopen.html @@ -0,0 +1,82 @@ + <h1 id="firstHeading" class="firstHeading">freopen, freopen_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 *freopen( const char *filename, const char *mode, + FILE *stream );</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 *freopen( const char *restrict filename, const char *restrict mode, + FILE *restrict stream );</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 freopen_s( FILE *restrict *restrict newstreamptr, + const char *restrict filename, const char *restrict mode, + FILE *restrict stream );</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> First, attempts to close the file associated with <code>stream</code>, ignoring any errors. Then, if <code>filename</code> is not null, attempts to open the file specified by <code>filename</code> using <code>mode</code> as if by <code><a href="fopen" title="c/io/fopen">fopen</a></code>, and associates that file with the file stream pointed to by <code>stream</code>. If <code>filename</code> is a null pointer, then the function attempts to reopen the file that is already associated with <code>stream</code> (it is implementation defined which mode changes are allowed in this case).</div> <div class="t-li1"> +<span class="t-li">2)</span> Same as <span class="t-v">(1)</span>, except that <code>mode</code> is treated as in <code>fopen_s</code> and that the pointer to the file stream is written to <code>newstreamptr</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: <dl> +<dd> +<ul> +<li> <code>newstreamptr</code> is a null pointer </li> +<li> <code>stream</code> is a null pointer </li> +<li> <code>mode</code> is a null pointer </li> +</ul> </dd> +<dd>As with all bounds-checked functions, <code>freopen_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>.</dd> +</dl> +</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 new <a href="#File_access_flags">file access mode</a> </td> +</tr> <tr class="t-par"> <td> stream </td> <td> - </td> <td> the file stream to modify </td> +</tr> <tr class="t-par"> <td> newstreamptr </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><a href="fopen" title="c/io/fopen">fopen</a></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> A copy of the value of <code>stream</code> on success, null pointer on failure.</div> <div class="t-li1"> +<span class="t-li">2)</span> zero on success (and a copy of the value of <code>stream</code> is written to <code>*newstreamptr</code>, non-zero on error (and null pointer is written to <code>*newstreamptr</code> unless <code>newstreamptr</code> is itself a null pointer).</div> <h3 id="Notes"> Notes</h3> <p><code>freopen</code> is the only way to change the narrow/wide orientation of a stream once it has been established by an I/O operation or by <code>fwide</code>.</p> +<p>Microsoft CRT version of <code>freopen</code> does not support any mode changes when <code>filename</code> is a null pointer and treats this as an error (see <a rel="nofollow" class="external text" href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/freopen-wfreopen">documentation</a>). A possible workaround is the non-standard function <a rel="nofollow" class="external text" href="https://docs.microsoft.com/en-us/cpp/c-runtime-library/reference/setmode"><code>_setmode()</code></a>.</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p>The following code redirects <code>stdout</code> to a file.</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + puts("stdout is printed to console"); + if (freopen("redir.txt", "w", stdout) == NULL) + { + perror("freopen() failed"); + return EXIT_FAILURE; + } + puts("stdout is redirected to a file"); // this is written to redir.txt + fclose(stdout); + return EXIT_SUCCESS; +}</pre></div> <p>Output:</p> +<div class="text source-text"><pre data-language="c">stdout is printed to console</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul> +<li> 7.21.5.4 The freopen function (p: 224-225) </li> +<li> K.3.5.2.2 The freopen_s function (p: 429-430) </li> +</ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul> +<li> 7.21.5.4 The freopen function (p: 307) </li> +<li> K.3.5.2.2 The freopen_s function (p: 590) </li> +</ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.5.4 The freopen function (p: 272-273) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.5.4 The freopen function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fopen" title="c/io/fopen"> <span class="t-lines"><span>fopen</span><span>fopen_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> opens a file <br> <span class="t-mark">(function)</span> </td> +</tr> <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 colspan="2"> <span><a href="https://en.cppreference.com/w/cpp/io/c/freopen" title="cpp/io/c/freopen">C++ documentation</a></span> for <code>freopen</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/freopen" class="_attribution-link">https://en.cppreference.com/w/c/io/freopen</a> + </p> +</div> |