std::basic_...buf::seekpos(3)

💅 std::basic_filebuf::seekpos 💅

okay so this page is from the C++ Standard Libary manual, and the header calls it std::basic_...buf::seekpos(3) — we're talking about std::basic_filebuf::seekpos, and it's literally the “put the file pointer where I say” member. bestie, it's protected and virtual, so it's giving backstage-pass energy. 🎟️✨

🎀 NAME 🎀

std::basic_filebuf::seekpos - std::basic_filebuf::seekpos

✨ Synopsis ✨

okay so the signature is protected and virtual, and yes, the default for which is the whole std::ios_base::in | std::ios_base::out combo:

protected:

virtual pos_type seekpos( pos_type sp,

                          std::ios_base::openmode which =
std::ios_base::in |
std::ios_base::out );

Repositions the file pointer, if possible, to the position indicated by sp. If the associated file is not open (is_open() == false), it fails immediately.

Reposition performs as follows:

1. If the file is open for writing, writes the put area and any unshift sequences required by the currently imbued locale, using overflow().
2. Repositions the file pointer, as if by calling std::fsetpos().
3. If the file is open for reading, updates the get area if necessary.

⚠️ if sp was not obtained by calling seekoff() or seekpos() on the same file, the behavior is undefined. that's the danger zone, bestie — do not freestyle this. 💀

🦋 Parameters 🦋

• sp — file position obtained by seekoff() or seekpos() called earlier on the same file.
• which — defines which of the input and/or output sequences to affect. It can be one or a combination of the following constants:
  • in — affect the input sequence
  • out — affect the output sequence

🎀 Return value 🎀

sp on success or pos_type(off_type(-1)) on failure. slay when it works, iconic failure value when it doesn't. 💅

🌸 Notes 🌸

seekpos() is called by std::basic_streambuf::pubseekpos(), which is called by the single-argument versions of std::basic_istream::seekg() and std::basic_ostream::seekp().

Many implementations do not update the get area in seekpos(), delegating to underflow() that is called by the next sgetc().

🧚 Example 🧚

On some implementations, the get area is emptied by seekpos() and the second underflow() is necessary to observe the effects.

// Run this code

#include <fstream>
#include <iostream>

struct mybuf : std::filebuf
{
    pos_type seekpos(pos_type sp, std::ios_base::openmode which)
    {
        std::cout << "Before seekpos(" << sp << "), size of the get area is "
                  << egptr() - eback() << " with "
                  << egptr() - gptr() << " read positions available.\n";

        pos_type rc = std::filebuf::seekpos(sp, which);

        std::cout << "seekpos() returns " << rc << ".\nAfter the call, "
                  << "size of the get area is "
                  << egptr() - eback() << " with "
                  << egptr() - gptr() << " read positions available.\n";
// uncomment if get area is emptied by seekpos()
//        std::filebuf::underflow();
//        std::cout << "after forced underflow(), size of the get area is "
//                  << egptr() - eback() << " with "
//                  << egptr() - gptr() << " read positions available.\n";

        return rc;
    }
};

int main()
{
    mybuf buf;
    buf.open("test.txt", std::ios_base::in);
    std::istream stream(&buf);
    stream.get(); // read one char to force underflow()
    stream.seekg(2);
}

Possible output:

Before seekpos(2), size of the get area is 110 with 109 read positions available.
seekpos() returns 2.
After the call, size of the get area is 110 with 108 read positions available.

💜 Defect reports 💜

The following behavior-changing defect reports were applied retroactively to previously published C++ standards.

• LWG 55, applied to C++98 — behavior as published: seekpos returned an undefined invalid stream position on failure. Correct behavior: pos_type(off_type(-1)) is returned on failure.
• LWG 171, applied to C++98 — behavior as published: the sequence of the operations of reposition was not clear. Correct behavior: made clear.

🌈 See also 🌈

• pubseekpos — invokes seekpos() (public member function of std::basic_streambuf<CharT,Traits>)
• seekoff — repositions the file position, using relative addressing [virtual] (virtual protected member function)
• fseek — moves the file position indicator to a specific location in a file (function)

mwah 💋 that's the whole page, bestie. source/version/date vibes: http://cppreference.com, 2024.06.10, page std::basic_...buf::seekpos(3). go touch grass now 🌱✨