diff options
Diffstat (limited to 'devdocs/c/io%2Ffseek.html')
| -rw-r--r-- | devdocs/c/io%2Ffseek.html | 74 |
1 files changed, 74 insertions, 0 deletions
diff --git a/devdocs/c/io%2Ffseek.html b/devdocs/c/io%2Ffseek.html new file mode 100644 index 00000000..0d57a3fe --- /dev/null +++ b/devdocs/c/io%2Ffseek.html @@ -0,0 +1,74 @@ + <h1 id="firstHeading" class="firstHeading">fseek</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"> <td class="t-dcl-nopad"> <pre data-language="c">int fseek( FILE *stream, long offset, int origin );</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> <tr class="t-dcl"> <td class="t-dcl-nopad"> <pre data-language="c">#define SEEK_SET /*unspecified*/ +#define SEEK_CUR /*unspecified*/ +#define SEEK_END /*unspecified*/</pre> +</td> <td class="t-dcl-nopad"> </td> <td class="t-dcl-nopad"> </td> </tr> </table> <p>Sets the file position indicator for the file stream <code>stream</code> to the value pointed to by <code>offset</code>.</p> +<p>If the <code>stream</code> is open in binary mode, the new position is exactly <code>offset</code> bytes measured from the beginning of the file if <code>origin</code> is <code><a href="../io" title="c/io">SEEK_SET</a></code>, from the current file position if <code>origin</code> is <code><a href="../io" title="c/io">SEEK_CUR</a></code>, and from the end of the file if <code>origin</code> is <code><a href="../io" title="c/io">SEEK_END</a></code>. Binary streams are not required to support <code><a href="../io" title="c/io">SEEK_END</a></code>, in particular if additional null bytes are output.</p> +<p>If the <code>stream</code> is open in text mode, the only supported values for <code>offset</code> are zero (which works with any <code>origin</code>) and a value returned by an earlier call to <code><a href="ftell" title="c/io/ftell">ftell</a></code> on a stream associated with the same file (which only works with <code>origin</code> of <code><a href="../io" title="c/io">SEEK_SET</a></code>).</p> +<p>If the <code>stream</code> is wide-oriented, the restrictions of both text and binary streams apply (result of <code><a href="ftell" title="c/io/ftell">ftell</a></code> is allowed with <code><a href="../io" title="c/io">SEEK_SET</a></code> and zero offset is allowed from <code><a href="../io" title="c/io">SEEK_SET</a></code> and <code><a href="../io" title="c/io">SEEK_CUR</a></code>, but not <code><a href="../io" title="c/io">SEEK_END</a></code>).</p> +<p>In addition to changing the file position indicator, <code>fseek</code> undoes the effects of <code><a href="ungetc" title="c/io/ungetc">ungetc</a></code> and clears the end-of-file status, if applicable.</p> +<p>If a read or write error occurs, the error indicator for the stream (<code><a href="ferror" title="c/io/ferror">ferror</a></code>) is set and the file position is unaffected.</p> +<h3 id="Parameters"> Parameters</h3> <table class="t-par-begin"> <tr class="t-par"> <td> stream </td> <td> - </td> <td> file stream to modify </td> +</tr> <tr class="t-par"> <td> offset </td> <td> - </td> <td> number of characters to shift the position relative to origin </td> +</tr> <tr class="t-par"> <td> origin </td> <td> - </td> <td> position to which <code>offset</code> is added. It can have one of the following values: <code><a href="../io" title="c/io">SEEK_SET</a></code>, <code><a href="../io" title="c/io">SEEK_CUR</a></code>, <code><a href="../io" title="c/io">SEEK_END</a></code> </td> +</tr> +</table> <h3 id="Return_value"> Return value</h3> <p><code>0</code> upon success, nonzero value otherwise.</p> +<h3 id="Notes"> Notes</h3> <p>After seeking to a non-end position in a wide stream, the next call to any output function may render the remainder of the file undefined, e.g. by outputting a multibyte sequence of a different length.</p> +<p>For text streams, the only valid values of <code>offset</code> are <code>0</code> (applicable to any <code>origin</code>) and a value returned by an earlier call to <code><a href="ftell" title="c/io/ftell">ftell</a></code> (only applicable to <code>SEEK_SET</code>).</p> +<p>POSIX allows seeking beyond the existing end of file. If an output is performed after this seek, any read from the gap will return zero bytes. Where supported by the filesystem, this creates a <i>sparse file</i>.</p> +<p>POSIX also requires that fseek first performs <code><a href="fflush" title="c/io/fflush">fflush</a></code> if there are any unwritten data (but whether the shift state is restored is implementation-defined).</p> +<h3 id="Example"> Example</h3> <div class="t-example"> +<p><code>fseek</code> with error checking:</p> +<div class="c source-c"><pre data-language="c">#include <stdio.h> +#include <stdlib.h> + +int main(void) +{ + /* Prepare an array of double values. */ + #define SIZE 5 + double A[SIZE] = {1.0, 2.0, 3.0, 4.0, 5.0}; + /* Write array to a file. */ + FILE * fp = fopen("test.bin", "wb"); + fwrite(A, sizeof(double), SIZE, fp); + fclose (fp); + + /* Read the double values into array B. */ + double B[SIZE]; + fp = fopen("test.bin", "rb"); + + /* Set the file position indicator in front of third double value. */ + if (fseek(fp, sizeof(double) * 2L, SEEK_SET) != 0) + { + fprintf(stderr, "fseek() failed in file %s at line # %d\n", __FILE__, __LINE__ - 2); + fclose(fp); + return EXIT_FAILURE; + } + + int ret_code = fread(B, sizeof(double), 1, fp); /* read one double value */ + printf("ret_code == %d\n", ret_code); /* print the number of values read */ + printf("B[0] == %.1f\n", B[0]); /* print one value */ + + fclose(fp); + return EXIT_SUCCESS; +}</pre></div> <p>Possible output:</p> +<div class="text source-text"><pre data-language="c">ret_code == 1 +B[0] == 3.0</pre></div> </div> <h3 id="References"> References</h3> <ul> +<li> C17 standard (ISO/IEC 9899:2018): </li> +<ul><li> 7.21.9.2 The fseek function (p: 245) </li></ul> +<li> C11 standard (ISO/IEC 9899:2011): </li> +<ul><li> 7.21.9.2 The fseek function (p: 336-337) </li></ul> +<li> C99 standard (ISO/IEC 9899:1999): </li> +<ul><li> 7.19.9.2 The fseek function (p: 302-303) </li></ul> +<li> C89/C90 standard (ISO/IEC 9899:1990): </li> +<ul><li> 4.9.9.2 The fseek function </li></ul> +</ul> <h3 id="See_also"> See also</h3> <table class="t-dsc-begin"> <tr class="t-dsc"> <td> <div><a href="fsetpos" title="c/io/fsetpos"> <span class="t-lines"><span>fsetpos</span></span></a></div> </td> <td> moves the file position indicator to a specific location in a file <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="fgetpos" title="c/io/fgetpos"> <span class="t-lines"><span>fgetpos</span></span></a></div> </td> <td> gets the file position indicator <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="ftell" title="c/io/ftell"> <span class="t-lines"><span>ftell</span></span></a></div> </td> <td> returns the current file position indicator <br> <span class="t-mark">(function)</span> </td> +</tr> <tr class="t-dsc"> <td> <div><a href="rewind" title="c/io/rewind"> <span class="t-lines"><span>rewind</span></span></a></div> </td> <td> moves the file position indicator to the beginning in 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/fseek" title="cpp/io/c/fseek">C++ documentation</a></span> for <code>fseek</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/fseek" class="_attribution-link">https://en.cppreference.com/w/c/io/fseek</a> + </p> +</div> |