IO::Poll(3pm)

💅 IO::Poll — like, the actual manual page, but make it make sense

okay bestie, welcome to IO::Poll(3pm), straight out of the Perl Programmers Reference Guide ✨ yes you read that right, this is a Perl core doc and we're about to make it cute. Also I didn't copy the header line, that's just where the manual name lives, mwah 🎀

---

🌸 NAME 🌸

IO::Poll — an object interface to the system poll call 🦋

like, the actual poll syscall but with a nice little object wrapper so you don't have to rawdog file descriptors. periodt.

---

✨ SYNOPSIS ✨

here's the vibe, copy-paste ready, no cap:

    use IO::Poll qw(POLLRDNORM POLLWRNORM POLLIN POLLHUP);

    $poll = IO::Poll->new();

    $poll->mask($input_handle => POLLIN);
    $poll->mask($output_handle => POLLOUT);

    $poll->poll($timeout);

    $ev = $poll->events($input);

see? it's giving "I know what I'm doing" energy 💅

---

🫶 DESCRIPTION 🫶

IO::Poll is a simple interface to the system level poll routine. that's it. that's the whole thing. it does NOT overcomplicate your life, it just hands you the poll call with a bow on top 🎀

---

👑 METHODS 👑

🍓 mask ( IO [, EVENT_MASK ] )

okay so here's the deal:

• if EVENT_MASK is given, then — as long as EVENT_MASK is non-zero — IO gets added to the list of file descriptors, and the next call to poll will check for any event specified in EVENT_MASK. ✨
• if EVENT_MASK is zero, then IO gets removed from the list of file descriptors. bye bestie 👋
• if EVENT_MASK is not given at all, then the return value will be the current event mask value for IO. so it's a little getter in that case, iykyk 💖

🌈 poll ( [ TIMEOUT ] )

this one calls the system level poll routine. fr fr.

if TIMEOUT is not specified then the call will block (yes, like block block, it will sit there and wait, main character energy but make it patient 😭).

returns the number of handles which had events happen, or -1 on error. 💀

💜 events ( IO )

returns the event mask which represents the events that happened on IO during the last call to poll. that's the tea 🍵

🧚 remove ( IO )

removes IO from the list of file descriptors for the next poll. clean, simple, iconic. 🌸

⭐ handles( [ EVENT_MASK ] )

returns a list of handles. here's the nuance bestie:

• if EVENT_MASK is not given, then you get a list of all handles known. the whole squad 🫶
• if EVENT_MASK is given, then you get a list of handles which had one of the events specified by EVENT_MASK happen during the last call to poll. the filtered squad, the ones who actually showed up 🔥

---

🦋 SEE ALSO 🦋

go read these next, no seriously:

• poll(2)
• IO::Handle
• IO::Select

---

🎀 AUTHOR 🎀

Graham Barr. currently maintained by the Perl Porters.

please report all bugs at <https://github.com/Perl/perl5/issues> — they want to hear from you, genuinely 🙈

---

💖 COPYRIGHT 💖

Copyright (c) 1997-8 Graham Barr <gbarr@pobox.com>. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 👑

---

lowkey the most important part: this is perl v5.42.3, dated 2026-11-03, and the page is IO::Poll(3pm). screenshot it, cite it, slay 💅✨