IO::Poll(3perl)

💖 IO::Poll — bestie edition 💖

okay so this is IO::Poll, and it's literally the object interface to the system poll call. it's from the Perl Programmers Reference Guide, it lives in section 3perl, and it's about to make your file-descriptor-wrangling life SO much cuter. 🦋

---

✨ SYNOPSIS ✨

    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);

that's the whole vibe bestie. hand it some handles, give them a mask, poll it, read the events. iconic behavior. 💅

---

🌸 DESCRIPTION 🌸

IO::Poll is a simple interface to the system level poll routine. that's it. that's the pitch. no cap, it's just a nice little Perl-y wrapper so you don't have to scream at syscalls directly. 🫶

---

👑 METHODS 👑

💜 mask ( IO [, EVENT_MASK ] )

if EVENT_MASK is given, then — and this is the important part — if EVENT_MASK is non-zero, then IO gets added to the list of file descriptors, and the next call to poll will be checking 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 just be the current event mask value for IO. a little peek, no changes. 🍓

🌈 poll ( [ TIMEOUT ] )

this calls the system level poll routine. if TIMEOUT isn't specified, heads up, the call will block — like, it will sit there and wait, no thoughts, head empty, until something happens. 😭

it returns the number of handles which had events happen, or -1 on error. that's the whole return contract, fr fr.

🦋 events ( IO )

returns the event mask which represents the events that happened on IO during the last call to poll. it's giving "receipts from last time." 🧚

⭐ remove ( IO )

removes IO from the list of file descriptors for the next poll. no more drama for that handle. periodt. 💅

💖 handles( [ EVENT_MASK ] )

returns a list of handles.

• if EVENT_MASK is not given, you get a list of all handles known. the whole squad.
• if EVENT_MASK is given, you get a list of handles which had one of the events specified by EVENT_MASK happen during the last call to poll. only the ones that actually popped off. 🔥

---

🔍 SEE ALSO 🔍

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

go read those too, bestie, iykyk. 📚

---

💌 AUTHOR 💌

Graham Barr. currently maintained by the Perl Porters. please report all bugs at <https://github.com/Perl/perl5/issues> — like, actually do it, they want to hear from you. 🫶

---

©️ 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.

---

and that's the whole page, bestie!! this lil masterpiece is from perl v5.44.0, dated 2026-10-17, and it's page IO::Poll(3perl) of the Perl Programmers Reference Guide. slay, go poll something. 💖✨🎀🦋🌸💅🫶