Difference between revisions of "cpp/io/c/fseek"

Latest revision as of 00:02, 14 May 2024

Defined in header `<cstdio>`
int fseek( std::FILE* stream, long offset, int origin );

Sets the file position indicator for the file stream stream.

If the stream is open in binary mode, the new position is exactly offset bytes measured from the beginning of the file if origin is SEEK_SET, from the current file position if origin is SEEK_CUR, and from the end of the file if origin is SEEK_END. Binary streams are not required to support SEEK_END, in particular if additional null bytes are output.

If the stream is open in text mode, the only supported values for offset are zero (which works with any origin) and a value returned by an earlier call to std::ftell on a stream associated with the same file (which only works with origin of SEEK_SET).

If the stream is wide-oriented, the restrictions of both text and binary streams apply (result of std::ftell is allowed with SEEK_SET and zero offset is allowed from SEEK_SET and SEEK_CUR, but not SEEK_END).

In addition to changing the file position indicator, fseek undoes the effects of std::ungetc and clears the end-of-file status, if applicable.

If a read or write error occurs, the error indicator for the stream (std::ferror) is set and the file position is unaffected.

#include <cassert>
#include <cstdio>
#include <cstdint>
#include <fstream>
#include <vector>
 
int main()
{
    std::ofstream("dummy.nfo") << "8 bytes\n"; // create the file
 
    std::FILE* fp = std::fopen("dummy.nfo", "rb");
    assert(fp);
 
    std::fseek(fp, 0, SEEK_END); // seek to end
    const std::size_t filesize = std::ftell(fp);
    std::vector<std::uint8_t> buffer(filesize);
 
    std::fseek(fp, 0, SEEK_SET); // seek to start
    std::fread(buffer.data(), sizeof(std::uint8_t), buffer.size(), fp);
 
    std::fclose(fp);
    std::printf("I've read %zi bytes\n", filesize);
}

Possible output:

I've read 8 bytes

[edit] See also

fsetpos	moves the file position indicator to a specific location in a file (function) [edit]
fgetpos	gets the file position indicator (function) [edit]
ftell	returns the current file position indicator (function) [edit]
rewind	moves the file position indicator to the beginning in a file (function) [edit]
C documentation for fseek

@@ Line 1: / Line 1: @@
-{{cpp/title | fseek }}
+{{cpp/title|fseek}}
-{{cpp/io/c/sidebar}}
+{{cpp/io/c/navbar}}
-{{ddcl | header=cstdio |
+{{ddcl|header=cstdio|
-int fseek( FILE *stream, long offset, int origin );
+int fseek( std::FILE* stream, long offset, int origin );
 }}
-Sets the file position indicator for the file stream {{tt|stream}} to the value pointed to by {{tt|pos}}. This function can be used to set the indicator beyond the actual end of the file, however, negative position values are not accepted.
+Sets the file position indicator for the file stream {{c|stream}}.
+If the {{c|stream}} is open in binary mode, the new position is exactly {{c|offset}} bytes measured from the beginning of the file if {{c|origin}} is {{lc|SEEK_SET}}, from the current file position if {{c|origin}} is {{lc|SEEK_CUR}}, and from the end of the file if {{c|origin}} is {{lc|SEEK_END}}. Binary streams are not required to support {{lc|SEEK_END}}, in particular if additional null bytes are output.
+If the {{c|stream}} is open in text mode, the only supported values for {{c|offset}} are zero (which works with any {{c|origin}}) and a value returned by an earlier call to {{lc|std::ftell}} on a stream associated with the same file (which only works with {{c|origin}} of {{lc|SEEK_SET}}).
+If the {{c|stream}} is wide-oriented, the restrictions of both text and binary streams apply (result of {{lc|std::ftell}} is allowed with {{lc|SEEK_SET}} and zero offset is allowed from {{lc|SEEK_SET}} and {{lc|SEEK_CUR}}, but not {{lc|SEEK_END}}).
+In addition to changing the file position indicator, {{tt|fseek}} undoes the effects of {{lc|std::ungetc}} and clears the end-of-file status, if applicable.
+If a read or write error occurs, the error indicator for the stream ({{lc|std::ferror}}) is set and the file position is unaffected.
 ===Parameters===
-{{param list begin}}
+{{par begin}}
-{{param list item | stream | file stream to modify}}
+{{par|stream|file stream to modify}}
-{{param list item | offset | number of characters to shift the position relative to origin}}
+{{par|offset|number of characters to shift the position relative to origin}}
-{{param list item | origin | position to which {{tt|offset}} is added. It can have one of the following values: {{c|SEEK_SET}}, {{c|SEEK_CUR}}, {{c|SEEK_END}}}}
+{{par|origin|position to which {{c|offset}} is added. It can have one of the following values: {{lc|SEEK_SET}}, {{lc|SEEK_CUR}}, {{lc|SEEK_END}}}}
-{{param list end}}
+{{par end}}
 ===Return value===
+{{c|0}} upon success, nonzero value otherwise.
-{{c|0}} upon success, nonzero value otherwise. Associated {{c|EOF}} flag is cleared for the stream and the effect of any {{c|std::ungetc}} is undone.
 ===Notes===
-For text streams, the only valid values of {{tt|offset}} are {{c|0}} (applicable to any {{tt|origin}}) and a value returned by an earlier call to {{c|std::ftell}} (only applicable to {{tt|SEEK_SET}}).
+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.
+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 ''sparse file''.
+POSIX also requires that {{tt|fseek}} first performs {{lc|std::fflush|fflush}} if there are any unwritten data (but whether the shift state is restored is implementation-defined). The standard C++ file streams guarantee both flushing and unshifting: {{lc|std::basic_filebuf::seekoff}}.
+POSIX specifies, that [https://pubs.opengroup.org/onlinepubs/9699919799/functions/fseek.html {{tt|fseek}}] should return {{c|-1}} on error, and set {{lc|errno}} to indicate the error.
+===Example===
+{{example
+|code=
+#include <cassert>
+#include <cstdio>
+#include <cstdint>
+#include <fstream>
+#include <vector>
+int main()
+{
+    std::ofstream("dummy.nfo") << "8 bytes\n"; // create the file
+    std::FILE* fp = std::fopen("dummy.nfo", "rb");
+    assert(fp);
+    std::fseek(fp, 0, SEEK_END); // seek to end
+    const std::size_t filesize = std::ftell(fp);
+    std::vector<std::uint8_t> buffer(filesize);
+    std::fseek(fp, 0, SEEK_SET); // seek to start
+    std::fread(buffer.data(), sizeof(std::uint8_t), buffer.size(), fp);
+    std::fclose(fp);
+    std::printf("I've read %zi bytes\n", filesize);
+}
+|p=true
+|output=
+I've read 8 bytes
+}}
 ===See also===
-{{dcl list begin}}
+{{dsc begin}}
-{{dcl list template | cpp/io/c/dcl list fsetpos}}
+{{dsc inc|cpp/io/c/dsc fsetpos}}
-{{dcl list template | cpp/io/c/dcl list fgetpos}}
+{{dsc inc|cpp/io/c/dsc fgetpos}}
-{{dcl list template | cpp/io/c/dcl list ftell}}
+{{dsc inc|cpp/io/c/dsc ftell}}
-{{dcl list template | cpp/io/c/dcl list rewind}}
+{{dsc inc|cpp/io/c/dsc rewind}}
-{{dcl list end}}
+{{dsc see c|c/io/fseek}}
+{{dsc end}}
-[[fr:cpp/io/c/fseek]]
+{{langlinks|de|es|fr|it|ja|pt|ru|zh}}
-[[ja:cpp/io/c/fseek]]
-[[zh:cpp/io/c/fseek]]

Compiler support
Freestanding and hosted
Language
Standard library
Standard library headers
Named requirements
Feature test macros (C++20)
Language support library
Concepts library (C++20)
Metaprogramming library (C++11)
Diagnostics library
General utilities library
Strings library
Containers library
Iterators library
Ranges library (C++20)
Algorithms library
Numerics library
Localizations library
Input/output library
Filesystem library (C++17)
Regular expressions library (C++11)
Concurrency support library (C++11)
Execution support library (C++26)
Technical specifications
Symbols index
External libraries

I/O manipulators
Print functions (C++23)
C-style I/O
Buffers
basic_streambuf
basic_filebuf
basic_stringbuf
basic_spanbuf (C++23)
strstreambuf (C++98/26*)
basic_syncbuf (C++20)
Streams
Abstractions
ios_base
basic_ios
basic_istream
basic_ostream
basic_iostream
File I/O
basic_ifstream
basic_ofstream
basic_fstream
String I/O
basic_istringstream
basic_ostringstream
basic_stringstream
Array I/O
basic_ispanstream (C++23)
basic_ospanstream (C++23)
basic_spanstream (C++23)
istrstream (C++98/26*)
ostrstream (C++98/26*)
strstream (C++98/26*)
Synchronized Output
basic_osyncstream (C++20)
Types
streamoff
streamsize
fpos
Error category interface
iostream_category (C++11)
io_errc (C++11)

cppreference.com

Namespaces

Variants

Views

Actions

Difference between revisions of "cpp/io/c/fseek"

Latest revision as of 00:02, 14 May 2024

Contents

[edit] Parameters

[edit] Return value

[edit] Notes

[edit] Example

[edit] See also

Navigation

Toolbox

stream	-	file stream to modify
offset	-	number of characters to shift the position relative to origin
origin	-	position to which offset is added. It can have one of the following values: SEEK_SET, SEEK_CUR, SEEK_END