IO::Seekable(3perl)

💖 IO::Seekable 💖

okay so bestie, welcome to IO::Seekable — the manual page, the legend, the one that supplies seek based methods for I/O objects. yes that's literally the whole name of the game. sit down, grab a strawberry 🍓, we're doing this.

---

✨ SYNOPSIS ✨

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

that's it. that's the whole vibe check. you inherit it. you don't instantiate it. iykyk.

---

🌸 DESCRIPTION 🌸

so IO::Seekable does not have a constructor of its own, and no that's not a bug, that's the point 💅 — it's meant to be inherited by other IO::Handle based objects. what it does bring to the group chat is a whole set of methods that let you seek around in file descriptors. main character energy, honestly.

$io->getpos

returns an opaque value that represents the current position of the IO::File — like, we're not gonna explain what's inside it, it's opaque, mind your business 🫶

and if that's not possible? say, on an unseekable stream like a terminal, a pipe, or a socket? you get undef. sorry bestie, no position for you.

fun detail: if the fgetpos() function is available in your C library, that's what gets used to implement getpos. otherwise, perl emulates getpos using C's ftell() function. either way, you get your position. slay.

$io->setpos

takes the value from a previous getpos call and teleports you back to a position you've already visited 🦋 iconic behavior.

returns "0 but true" on success, and undef on failure. not 0, not 1 — "0 but true". that's not a typo, that's perl being perl 💀

---

now. for the complete descriptions of each of the following supported IO::Seekable methods, go peek at perlfunc — because these are, fr fr, just front ends for the corresponding built-in functions. no cap.

$io->seek ( POS, WHENCE )

seeks the IO::File to position POS, relative to WHENCE. and WHENCE is giving options, so let's break it down:

• WHENCE=0 (SEEK_SET) — POS is an absolute position. (Seek relative to the start of the file.) the classic. the beginning. the origin story ✨
• WHENCE=1 (SEEK_CUR) — POS is an offset from the current position. (Seek relative to current.) you're already somewhere, now scoot.
• WHENCE=2 (SEEK_END) — POS is an offset from the end of the file. (Seek relative to end.) usually a negative number, just saying.

and if you don't wanna be out here writing 0, 1, or 2 in your code like a caveman, the SEEK_* constants can be imported from the Fcntl module. do that. your future self says thank you 🫶

returns 1 upon success, 0 otherwise. that's the whole deal.

$io->sysseek( POS, WHENCE )

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

⚠️ okay so like, read that again bestie. sysseek and regular perl IO are not on speaking terms. if you mix them, things get weird. sysread and syswrite only. periodt.

returns the new position, or undef on failure. and — plot twist — a position of zero is returned as the string "0 but true". again. not a typo. it's giving iconic. 💅

$io->tell

returns the IO::File's current position, or -1 on error. short, sweet, does exactly what it says. 👑

---

🌈 SEE ALSO 🌈

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

go read those too, bestie. knowledge is free and it's cute to know things 🎀

---

📜 HISTORY 📜

derived from FileHandle.pm by Graham Barr <gbarr@pobox.com>. we stan a foundational contribution 🫡

---

and that's the whole page, babe. this was perl v5.44.0, dated 2026-10-17, from the Perl Programmers Reference Guide, and it's part of the IO::Seekable(3perl) manual — the one and only. now go seek responsibly 💖✨🦋