IO::Seekable(3pm)

💖 IO::Seekable 💖

okay so this is the IO::Seekable page from the Perl Programmers Reference Guide (that's the 3pm one, yes bestie, the perl docs) — and it's literally all about teaching your I/O objects how to move around in a file. no cap, this is the seek queen's origin story 🎀

---

✨ NAME ✨

IO::Seekable — the module that supplies seek-based methods for I/O objects. that's it, that's the whole vibe. 🦋

---

🌸 SYNOPSIS 🌸

use IO::Seekable;
package IO::Something;
@ISA = qw(IO::Seekable);

like, you don't call it directly — you inherit from it. periodt. 💅

---

💅 DESCRIPTION 💅

so here's the tea: IO::Seekable does not have a constructor of its own — nope, none, it's not that kind of module. it's intended to be inherited by other IO::Handle based objects. it's giving supporting-character-with-main-character-energy, honestly. 🫶

what it does do is give you methods that let you seek around the file descriptors. iconic behaviour.

🎀 $io->getpos

returns an opaque value that represents the current position of the IO::File — or undef if that's not possible (eg. an unseekable stream such as a terminal, pipe or socket — yeah, some things just don't wanna be seeked, and that's valid 😭).

fun implementation detail: if the fgetpos() function is available in your C library, it's used to implement getpos; otherwise perl emulates getpos using C's ftell() function. lowkey clever ngl. ✨

🎀 $io->setpos

uses the value from a previous getpos call to return to a previously visited position — like a little bookmark but make it ✨time travel✨.

returns "0 but true" on success, "undef" on failure. yes, "0 but true" is a real string that's true and also zero, and it ate. 🔥

---

so basically, for complete descriptions of each of the following supported IO::Seekable methods, you wanna peek at perlfunc — because these are literally just front ends for the corresponding built-in functions. same energy, new wrapper. 💜

🎀 $io->seek ( POS, WHENCE )

seeks the IO::File to position POS, relative to WHENCE. here's the WHENCE lore:

• WHENCE=0 (SEEK_SET) — POS is absolute position. (seek relative to the start of the file 👑)
• WHENCE=1 (SEEK_CUR) — POS is an offset from the current position. (seek relative to current 🌀)
• WHENCE=2 (SEEK_END) — POS is an offset from the end of the file. (seek relative to end 🏁)

the SEEK_* constants can be imported from the Fcntl module if you don't wish to use the numbers 0 1 or 2 in your code — honestly bestie, use the constants, your future self will thank you 🙈

returns 1 upon success, 0 otherwise.

🎀 $io->sysseek( POS, WHENCE )

similar to $io->seek, but it sets the IO::File's position using the system call lseek(2) directly — so it will confuse most perl IO operators except sysread and syswrite (see perlfunc for full details).

fr fr, this one is a little unhinged: it bypasses the normal buffering, so mixing it with regular IO is asking for chaos 💀 you've been warned, bestie.

returns the new position, or undef on failure. a position of zero is returned as the string "0 but true" — she's back, the icon, the legend. ⭐

🎀 $io->tell

returns the IO::File's current position, or -1 on error. short, sweet, slays. 🌈

---

🦋 SEE ALSO 🦋

perlfunc, "I/O Operators" in perlop, IO::Handle IO::File

(go read them, iykyk 📚)

---

👑 HISTORY 👑

derived from FileHandle.pm by Graham Barr <gbarr@pobox.com> — thank you for your service, king 🫡

---

and that's the page, bestie!! ✨ this was the IO::Seekable(3pm) manpage, straight out of the Perl Programmers Reference Guide, from perl v5.42.3, dated 2026-11-03. go forth and seek responsibly 💖🎀🌸