C++

Reference

<istream>

istream

public member function
<istream> <iostream>

std::istream::seekg

(1)
istream& seekg (streampos pos);
(2)
istream& seekg (streamoff off, ios_base::seekdir way);
Set position in input sequence
Sets the position of the next character to be extracted from the input stream.

Internally, the function accesses the input sequence by first constructing a sentry object (with noskipws set to true). Then (if good), it calls either pubseekpos (1) or pubseekoff (2) on its associated stream buffer object (if any). Finally, it destroys the sentry object before returning.

If the eofbit flag is set before the call, the function fails (sets failbit and returns).
The function clears the eofbit flag, if set before the call.

Calling this function does not alter the value returned by gcount.

Parameters

pos
New absolute position within the stream (relative to the beginning).
streampos is an fpos type (it can be converted to/from integral types).
off
Offset value, relative to the way parameter.
streamoff is an offset type (generally, a signed integral type).
way
Object of type ios_base::seekdir. It may take any of the following constant values:
valueoffset is relative to...
ios_base::begbeginning of the stream
ios_base::curcurrent position in the stream
ios_base::endend of the stream

Return Value

The istream object (*this).

Errors are signaled by modifying the internal state flags:
flagerror
eofbit-
failbitEither the construction of sentry failed, or the internal call to pubseekpos (1) or pubseekoff (2) failed (i.e., either function returned -1).
badbitAnother error occurred on the stream (such as when the function catches an exception thrown by an internal operation).
When set, the integrity of the stream may have been affected.
Multiple flags may be set by a single operation.

If the operation sets an internal state flag that was registered with member exceptions, the function throws an exception of member type failure.

Example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
 
// read a file into memory
#include <iostream>     // std::cout
#include <fstream>      // std::ifstream

int main () {
  std::ifstream is ("test.txt", std::ifstream::binary);
  if (is) {
    // get length of file:
    is.seekg (0, is.end);
    int length = is.tellg();
    is.seekg (0, is.beg);

    // allocate memory:
    char * buffer = new char [length];

    // read data as a block:
    is.read (buffer,length);

    is.close();

    // print content:
    std::cout.write (buffer,length);

    delete[] buffer;
  }

  return 0;
}

In this example, seekg is used to move the position to the end of the file, and then back to the beginning.

Data races

Modifies the stream object.
Concurrent access to the same stream object may cause data races.

Exception safety

Basic guarantee: if an exception is thrown, the object is in a valid state.
It throws an exception of member type failure if the resulting error state flag is not goodbit and member exceptions was set to throw for that state.
Any exception thrown by an internal operation is caught and handled by the function, setting badbit. If badbit was set on the last call to exceptions, the function rethrows the caught exception.

See also

istream::tellg
Get position in input sequence (public member function)
ostream::seekp
Set position in output sequence (public member function)