.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "IO::Async::OS 3pm"
.TH IO::Async::OS 3pm 2024-02-04 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
"IO::Async::OS" \- operating system abstractions for "IO::Async"
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module acts as a class to provide a number of utility methods whose exact
behaviour may depend on the type of OS it is running on. It is provided as a
class so that specific kinds of operating system can override methods in it.
.PP
As well as these support functions it also provides a number of constants, all
with names beginning \f(CW\*(C`HAVE_\*(C'\fR which describe various features that may or may
not be available on the OS or perl build. Most of these are either hard-coded
per OS, or detected at runtime.
.PP
The following constants may be overridden by environment variables.
.IP \(bu 4
HAVE_POSIX_FORK
.Sp
True if the \f(CWfork()\fR call has full POSIX semantics (full process separation).
This is true on most OSes but false on MSWin32.
.Sp
This may be overridden to be false by setting the environment variable
\&\f(CW\*(C`IO_ASYNC_NO_FORK\*(C'\fR.
.IP \(bu 4
HAVE_THREADS
.Sp
True if \f(CW\*(C`ithreads\*(C'\fR are available, meaning that the \f(CW\*(C`threads\*(C'\fR module can be
used. This depends on whether perl was built with threading support.
.Sp
This may be overridable to be false by setting the environment variable
\&\f(CW\*(C`IO_ASYNC_NO_THREADS\*(C'\fR.
.SS getfamilybyname
.IX Subsection "getfamilybyname"
.Vb 1
\&   $family = IO::Async::OS\->getfamilybyname( $name )
.Ve
.PP
Return a protocol family value based on the given name. If \f(CW$name\fR looks like
a number it will be returned as-is. The string values \f(CW\*(C`inet\*(C'\fR, \f(CW\*(C`inet6\*(C'\fR and
\&\f(CW\*(C`unix\*(C'\fR will be converted to the appropriate \f(CW\*(C`AF_*\*(C'\fR constant.
.SS getsocktypebyname
.IX Subsection "getsocktypebyname"
.Vb 1
\&   $socktype = IO::Async::OS\->getsocktypebyname( $name );
.Ve
.PP
Return a socket type value based on the given name. If \f(CW$name\fR looks like a
number it will be returned as-is. The string values \f(CW\*(C`stream\*(C'\fR, \f(CW\*(C`dgram\*(C'\fR and
\&\f(CW\*(C`raw\*(C'\fR will be converted to the appropriate \f(CW\*(C`SOCK_*\*(C'\fR constant.
.SS socketpair
.IX Subsection "socketpair"
.Vb 1
\&   ( $S1, $S2 ) = IO::Async::OS\->socketpair( $family, $socktype, $proto );
.Ve
.PP
An abstraction of the \f(CWsocketpair(2)\fR syscall, where any argument may be
missing (or given as \f(CW\*(C`undef\*(C'\fR).
.PP
If \f(CW$family\fR is not provided, a suitable value will be provided by the OS
(likely \f(CW\*(C`AF_UNIX\*(C'\fR on POSIX-based platforms). If \f(CW$socktype\fR is not provided,
then \f(CW\*(C`SOCK_STREAM\*(C'\fR will be used.
.PP
Additionally, this method supports building connected \f(CW\*(C`SOCK_STREAM\*(C'\fR or
\&\f(CW\*(C`SOCK_DGRAM\*(C'\fR pairs in the \f(CW\*(C`AF_INET\*(C'\fR family even if the underlying platform's
\&\f(CWsocketpair(2)\fR does not, by connecting two normal sockets together.
.PP
\&\f(CW$family\fR and \f(CW$socktype\fR may also be given symbolically as defined by
\&\f(CW\*(C`getfamilybyname\*(C'\fR and \f(CW\*(C`getsocktypebyname\*(C'\fR.
.SS pipepair
.IX Subsection "pipepair"
.Vb 1
\&   ( $rd, $wr ) = IO::Async::OS\->pipepair;
.Ve
.PP
An abstraction of the \f(CWpipe(2)\fR syscall, which returns the two new handles.
.SS pipequad
.IX Subsection "pipequad"
.Vb 1
\&   ( $rdA, $wrA, $rdB, $wrB ) = IO::Async::OS\->pipequad;
.Ve
.PP
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, \f(CW$rdA\fR and \f(CW$wrA\fR will be a linked pair, as
will \f(CW$rdB\fR and \f(CW$wrB\fR.
.PP
On platforms that support \f(CWsocketpair(2)\fR, this implementation will be
preferred, in which case \f(CW$rdA\fR and \f(CW$wrB\fR will actually be the same
filehandle, as will \f(CW$rdB\fR and \f(CW$wrA\fR. This saves a file descriptor in the
parent process.
.PP
When creating a IO::Async::Stream or subclass of it, the \f(CW\*(C`read_handle\*(C'\fR
and \f(CW\*(C`write_handle\*(C'\fR parameters should always be used.
.PP
.Vb 1
\&   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 );
.Ve
.SS signame2num
.IX Subsection "signame2num"
.Vb 1
\&   $signum = IO::Async::OS\->signame2num( $signame );
.Ve
.PP
This utility method converts a signal name (such as "TERM") into its system\-
specific signal number. This may be useful to pass to \f(CW\*(C`POSIX::SigSet\*(C'\fR or use
in other places which use numbers instead of symbolic names.
.SS signum2name
.IX Subsection "signum2name"
.Vb 1
\&   $signame = IO::Async::OS\->signum2name( $signum );
.Ve
.PP
The inverse of signame2num; this method convers signal numbers into
readable names.
.SS extract_addrinfo
.IX Subsection "extract_addrinfo"
.Vb 1
\&   ( $family, $socktype, $protocol, $addr ) = IO::Async::OS\->extract_addrinfo( $ai );
.Ve
.PP
Given an ARRAY or HASH reference value containing an addrinfo, returns a
family, socktype and protocol argument suitable for a \f(CW\*(C`socket\*(C'\fR call and an
address suitable for \f(CW\*(C`connect\*(C'\fR or \f(CW\*(C`bind\*(C'\fR.
.PP
If given an ARRAY it should be in the following form:
.PP
.Vb 1
\&   [ $family, $socktype, $protocol, $addr ]
.Ve
.PP
If given a HASH it should contain the following keys:
.PP
.Vb 1
\&   family socktype protocol addr
.Ve
.PP
Each field in the result will be initialised to 0 (or empty string for the
address) if not defined in the \f(CW$ai\fR value.
.PP
The family type may also be given as a symbolic string as defined by
\&\f(CW\*(C`getfamilybyname\*(C'\fR.
.PP
The socktype may also be given as a symbolic string; \f(CW\*(C`stream\*(C'\fR, \f(CW\*(C`dgram\*(C'\fR or
\&\f(CW\*(C`raw\*(C'\fR; this will be converted to the appropriate \f(CW\*(C`SOCK_*\*(C'\fR constant.
.PP
Note that the \f(CW\*(C`addr\*(C'\fR field, if provided, must be a packed socket address,
such as returned by \f(CW\*(C`pack_sockaddr_in\*(C'\fR or \f(CW\*(C`pack_sockaddr_un\*(C'\fR.
.PP
If the HASH form is used, rather than passing a packed socket address in the
\&\f(CW\*(C`addr\*(C'\fR field, certain other hash keys may be used instead for convenience on
certain named families.
.IP "family => 'inet'" 4
.IX Item "family => 'inet'"
Will pack an IP address and port number from keys called \f(CW\*(C`ip\*(C'\fR and \f(CW\*(C`port\*(C'\fR.
If \f(CW\*(C`ip\*(C'\fR is missing it will be set to "0.0.0.0". If \f(CW\*(C`port\*(C'\fR is missing it will
be set to 0.
.IP "family => 'inet6'" 4
.IX Item "family => 'inet6'"
Will pack an IP address and port number from keys called \f(CW\*(C`ip\*(C'\fR and \f(CW\*(C`port\*(C'\fR.
If \f(CW\*(C`ip\*(C'\fR is missing it will be set to "::". If \f(CW\*(C`port\*(C'\fR is missing it will be
set to 0. Optionally will also include values from \f(CW\*(C`scopeid\*(C'\fR and \f(CW\*(C`flowinfo\*(C'\fR
keys if provided.
.Sp
This will only work if a \f(CW\*(C`pack_sockaddr_in6\*(C'\fR function can be found in
\&\f(CW\*(C`Socket\*(C'\fR
.IP "family => 'unix'" 4
.IX Item "family => 'unix'"
Will pack a UNIX socket path from a key called \f(CW\*(C`path\*(C'\fR.
.SS make_addr_for_peer
.IX Subsection "make_addr_for_peer"
.Vb 1
\&   $connectaddr = IO::Async::OS\->make_addr_for_peer( $family, $listenaddr );
.Ve
.PP
Given the \f(CW\*(C`sockdomain\*(C'\fR and \f(CW\*(C`sockname\*(C'\fR of a listening socket. creates an
address suitable to \f(CWconnect()\fR to it.
.PP
This method will handle specially any \f(CW\*(C`AF_INET\*(C'\fR address bound to
\&\f(CW\*(C`INADDR_ANY\*(C'\fR or any \f(CW\*(C`AF_INET6\*(C'\fR address bound to \f(CW\*(C`IN6ADDR_ANY\*(C'\fR, as some OSes
do not allow \f(CWconnect(2)\fRing to those and would instead insist on receiving
\&\f(CW\*(C`INADDR_LOOPBACK\*(C'\fR or \f(CW\*(C`IN6ADDR_LOOPBACK\*(C'\fR respectively.
.PP
This method is used by the \f(CW\*(C`\->connect( peer => $sock )\*(C'\fR parameter of
handle and loop connect methods.
.SH "LOOP IMPLEMENTATION METHODS"
.IX Header "LOOP IMPLEMENTATION METHODS"
The following methods are provided on \f(CW\*(C`IO::Async::OS\*(C'\fR 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 \f(CW\*(C`$loop\->{os}\*(C'\fR
to store other data it requires.
.SS loop_watch_signal
.IX Subsection "loop_watch_signal"
.SS loop_unwatch_signal
.IX Subsection "loop_unwatch_signal"
.Vb 1
\&   IO::Async::OS\->loop_watch_signal( $loop, $signal, $code );
\&
\&   IO::Async::OS\->loop_unwatch_signal( $loop, $signal );
.Ve
.PP
Used to implement the \f(CW\*(C`watch_signal\*(C'\fR / \f(CW\*(C`unwatch_signal\*(C'\fR Loop pair.
.SS potentially_open_fds
.IX Subsection "potentially_open_fds"
.Vb 1
\&   @fds = IO::Async::OS\->potentially_open_fds;
.Ve
.PP
Returns a list of filedescriptors which might need closing. By default this
will return \f(CW\*(C`0 .. _SC_OPEN_MAX\*(C'\fR. OS-specific subclasses may have a better
guess.
.SH AUTHOR
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>