IO::Async::OS(3pm)

✨ NAME ✨

IO::Async::OS — operating system abstractions for IO::Async 💅

---

🌸 DESCRIPTION 🌸

okay so bestie, this module is literally a class that hands you a whole pile of utility methods, and their exact behaviour may depend on the type of OS you're running on. no cap. and it's a class specifically so that specific kinds of operating system can override the methods in it — main character energy, honestly.

As well as these support functions, it also gives you a bunch of constants, all with names beginning HAVE_, which describe various features that may or may not be available on the OS or on your perl build. Most of these are either hard-coded per OS, or detected at runtime. detective work 🔍✨

The following constants may be overridden by environment variables 👀

• HAVE_POSIX_FORK — True if the fork() call has full POSIX semantics (full process separation). This is true on most OSes but false on MSWin32. This may be overridden to be false by setting the environment variable IO_ASYNC_NO_FORK.
• HAVE_THREADS — True if ithreads are available, meaning that the threads module can be used. This depends on whether perl was built with threading support. This may be overridable to be false by setting the environment variable IO_ASYNC_NO_THREADS.

---

🎀 getfamilybyname

$family = IO::Async::OS->getfamilybyname( $name )

Returns a protocol family value based on the given $name. If $name looks like a number it will be returned as-is, fr fr. The string values inet, inet6 and unix will be converted to the appropriate AF_* constant. converting vibes into numbers, we love to see it 🔥

🎀 getsocktypebyname

$socktype = IO::Async::OS->getsocktypebyname( $name );

Returns a socket type value based on the given $name. If $name looks like a number it will be returned as-is. The string values stream, dgram and raw will be converted to the appropriate SOCK_* constant. periodt 💜

🦋 socketpair

( $S1, $S2 ) = IO::Async::OS->socketpair( $family, $socktype, $proto );

An abstraction of the socketpair(2) syscall, where any argument may be missing (or given as undef). so chill of it.

If $family is not provided, a suitable value will be provided by the OS (likely AF_UNIX on POSIX-based platforms). If $socktype is not provided, then SOCK_STREAM will be used.

Additionally, this method supports building connected SOCK_STREAM or SOCK_DGRAM pairs in the AF_INET family even if the underlying platform's socketpair(2) does not, by connecting two normal sockets together. the way it just makes it work 😭👑

$family and $socktype may also be given symbolically as defined by getfamilybyname and getsocktypebyname.

🦋 pipepair

( $rd, $wr ) = IO::Async::OS->pipepair;

An abstraction of the pipe(2) syscall, which returns the two new handles. two little handles, one destiny 🫶

🦋 pipequad

( $rdA, $wrA, $rdB, $wrB ) = IO::Async::OS->pipequad;

This method is intended for creating two pairs of filehandles that are linked together, suitable for passing as the STDIN/STDOUT pair to a child process. After this function returns, $rdA and $wrA will be a linked pair, as will $rdB and $wrB.

On platforms that support socketpair(2), this implementation will be preferred, in which case $rdA and $wrB will actually be the same filehandle, as will $rdB and $wrA. This saves a file descriptor in the parent process. efficiency icon ✨

When creating a IO::Async::Stream or subclass of it, the read_handle and write_handle parameters should always be used.

my ( $childRd, $myWr, $myRd, $childWr ) = IO::Async::OS->pipequad;

$loop->open_process(
   stdin  => $childRd,
   stdout => $childWr,
   ...
);

my $str = IO::Async::Stream->new(
   read_handle  => $myRd,
   write_handle => $myWr,
   ...
);
$loop->add( $str );

like. look at that. beautiful. use it. 💖

🌈 signame2num

$signum = IO::Async::OS->signame2num( $signame );

This utility method converts a signal name (such as TERM) into its system-specific signal number. This may be useful to pass to POSIX::SigSet or use in other places which use numbers instead of symbolic names. names → numbers, the classic glow-up 💫

🌈 signum2name

$signame = IO::Async::OS->signum2name( $signum );

The inverse of signame2num; this method convers signal numbers into readable names. (yes bestie, that typo is in the original, and yes we're keeping it — every detail, no cap 🙈)

🧚 extract_addrinfo

( $family, $socktype, $protocol, $addr ) = IO::Async::OS->extract_addrinfo( $ai );

Given an ARRAY or HASH reference value containing an addrinfo, returns a family, socktype and protocol argument suitable for a socket call and an address suitable for connect or bind.

If given an ARRAY it should be in the following form:

[ $family, $socktype, $protocol, $addr ]

If given a HASH it should contain the following keys:

family socktype protocol addr

Each field in the result will be initialised to 0 (or empty string for the address) if not defined in the $ai value. no missing values on our watch 💅

The family type may also be given as a symbolic string as defined by getfamilybyname.

The socktype may also be given as a symbolic string; stream, dgram or raw; this will be converted to the appropriate SOCK_* constant.

⚠️ Note that the addr field, if provided, must be a packed socket address, such as returned by pack_sockaddr_in or pack_sockaddr_un. do not just vibe an unpacked string in there, bestie.

If the HASH form is used, rather than passing a packed socket address in the addr field, certain other hash keys may be used instead for convenience on certain named families.

• family => 'inet' — Will pack an IP address and port number from keys called ip and port. If ip is missing it will be set to 0.0.0.0. If port is missing it will be set to 0.
• family => 'inet6' — Will pack an IP address and port number from keys called ip and port. If ip is missing it will be set to ::. If port is missing it will be set to 0. Optionally will also include values from scopeid and flowinfo keys if provided. This will only work if a pack_sockaddr_in6 function can be found in Socket.
• family => 'unix' — Will pack a UNIX socket path from a key called path.

💜 make_addr_for_peer

$connectaddr = IO::Async::OS->make_addr_for_peer( $family, $listenaddr );

Given the sockdomain and sockname of a listening socket, creates an address suitable to connect() to it.

This method will handle specially any AF_INET address bound to INADDR_ANY or any AF_INET6 address bound to IN6ADDR_ANY, as some OSes do not allow connect(2)ing to those and would instead insist on receiving INADDR_LOOPBACK or IN6ADDR_LOOPBACK respectively. some OSes are so dramatic about it, honestly 😭

This method is used by the ->connect( peer => $sock ) parameter of handle and loop connect methods.

---

👑 LOOP IMPLEMENTATION METHODS 👑

The following methods are provided on IO::Async::OS because they are likely to require OS-specific implementations, but are used by IO::Async::Loop to implement its functionality. It can use the HASH reference $loop->{os} to store other data it requires. storing extra data in there like it's her little purse 💅

loop_watch_signal

loop_unwatch_signal

IO::Async::OS->loop_watch_signal( $loop, $signal, $code );

IO::Async::OS->loop_unwatch_signal( $loop, $signal );

Used to implement the watch_signal / unwatch_signal Loop pair. a duo, a matching set, iconic 🫶

potentially_open_fds

@fds = IO::Async::OS->potentially_open_fds;

Returns a list of filedescriptors which might need closing. By default this will return 0 .. _SC_OPEN_MAX. OS-specific subclasses may have a better guess. a little hint from the subclass, we love a helpful queen ⭐

---

🎀 AUTHOR 🎀

Paul Evans <leonerd@leonerd.org.uk> — thank you for your service, king 👑

---

and that's the whole thing, bestie!! this was perl v5.40.1, dated 2026-02-21, page IO::Async::OS(3pm) from the User Contributed Perl Documentation. go forth and abstract your operating system 💖✨🦋🌈🎀