1IO::Async::OS(3pm)    User Contributed Perl Documentation   IO::Async::OS(3pm)
2
3
4

NAME

6       "IO::Async::OS" - operating system abstractions for "IO::Async"
7

DESCRIPTION

9       This module acts as a class to provide a number of utility methods
10       whose exact behaviour may depend on the type of OS it is running on. It
11       is provided as a class so that specific kinds of operating system can
12       override methods in it.
13
14       As well as these support functions it also provides a number of
15       constants, all with names beginning "HAVE_" which describe various
16       features that may or may not be available on the OS or perl build. Most
17       of these are either hard-coded per OS, or detected at runtime.
18
19       The following constants may be overridden by environment variables.
20
21       •   HAVE_POSIX_FORK
22
23           True if the fork() call has full POSIX semantics (full process
24           separation).  This is true on most OSes but false on MSWin32.
25
26           This may be overridden to be false by setting the environment
27           variable "IO_ASYNC_NO_FORK".
28
29       •   HAVE_THREADS
30
31           True if "ithreads" are available, meaning that the "threads" module
32           can be used. This depends on whether perl was built with threading
33           support.
34
35           This may be overridable to be false by setting the environment
36           variable "IO_ASYNC_NO_THREADS".
37
38   getfamilybyname
39          $family = IO::Async::OS->getfamilybyname( $name )
40
41       Return a protocol family value based on the given name. If $name looks
42       like a number it will be returned as-is. The string values "inet",
43       "inet6" and "unix" will be converted to the appropriate "AF_*"
44       constant.
45
46   getsocktypebyname
47          $socktype = IO::Async::OS->getsocktypebyname( $name )
48
49       Return a socket type value based on the given name. If $name looks like
50       a number it will be returned as-is. The string values "stream", "dgram"
51       and "raw" will be converted to the appropriate "SOCK_*" constant.
52
53   socketpair
54          ( $S1, $S2 ) = IO::Async::OS->socketpair( $family, $socktype, $proto )
55
56       An abstraction of the socketpair(2) syscall, where any argument may be
57       missing (or given as "undef").
58
59       If $family is not provided, a suitable value will be provided by the OS
60       (likely "AF_UNIX" on POSIX-based platforms). If $socktype is not
61       provided, then "SOCK_STREAM" will be used.
62
63       Additionally, this method supports building connected "SOCK_STREAM" or
64       "SOCK_DGRAM" pairs in the "AF_INET" family even if the underlying
65       platform's socketpair(2) does not, by connecting two normal sockets
66       together.
67
68       $family and $socktype may also be given symbolically as defined by
69       "getfamilybyname" and "getsocktypebyname".
70
71   pipepair
72          ( $rd, $wr ) = IO::Async::OS->pipepair
73
74       An abstraction of the pipe(2) syscall, which returns the two new
75       handles.
76
77   pipequad
78          ( $rdA, $wrA, $rdB, $wrB ) = IO::Async::OS->pipequad
79
80       This method is intended for creating two pairs of filehandles that are
81       linked together, suitable for passing as the STDIN/STDOUT pair to a
82       child process.  After this function returns, $rdA and $wrA will be a
83       linked pair, as will $rdB and $wrB.
84
85       On platforms that support socketpair(2), this implementation will be
86       preferred, in which case $rdA and $wrB will actually be the same
87       filehandle, as will $rdB and $wrA. This saves a file descriptor in the
88       parent process.
89
90       When creating a IO::Async::Stream or subclass of it, the "read_handle"
91       and "write_handle" parameters should always be used.
92
93          my ( $childRd, $myWr, $myRd, $childWr ) = IO::Async::OS->pipequad;
94
95          $loop->open_process(
96             stdin  => $childRd,
97             stdout => $childWr,
98             ...
99          );
100
101          my $str = IO::Async::Stream->new(
102             read_handle  => $myRd,
103             write_handle => $myWr,
104             ...
105          );
106          $loop->add( $str );
107
108   signame2num
109          $signum = IO::Async::OS->signame2num( $signame )
110
111       This utility method converts a signal name (such as "TERM") into its
112       system- specific signal number. This may be useful to pass to
113       "POSIX::SigSet" or use in other places which use numbers instead of
114       symbolic names.
115
116   signum2name
117          $signame = IO::Async::OS->signum2name( $signum )
118
119       The inverse of signame2num; this method convers signal numbers into
120       readable names.
121
122   extract_addrinfo
123          ( $family, $socktype, $protocol, $addr ) = IO::Async::OS->extract_addrinfo( $ai )
124
125       Given an ARRAY or HASH reference value containing an addrinfo, returns
126       a family, socktype and protocol argument suitable for a "socket" call
127       and an address suitable for "connect" or "bind".
128
129       If given an ARRAY it should be in the following form:
130
131          [ $family, $socktype, $protocol, $addr ]
132
133       If given a HASH it should contain the following keys:
134
135          family socktype protocol addr
136
137       Each field in the result will be initialised to 0 (or empty string for
138       the address) if not defined in the $ai value.
139
140       The family type may also be given as a symbolic string as defined by
141       "getfamilybyname".
142
143       The socktype may also be given as a symbolic string; "stream", "dgram"
144       or "raw"; this will be converted to the appropriate "SOCK_*" constant.
145
146       Note that the "addr" field, if provided, must be a packed socket
147       address, such as returned by "pack_sockaddr_in" or "pack_sockaddr_un".
148
149       If the HASH form is used, rather than passing a packed socket address
150       in the "addr" field, certain other hash keys may be used instead for
151       convenience on certain named families.
152
153       family => 'inet'
154           Will pack an IP address and port number from keys called "ip" and
155           "port".  If "ip" is missing it will be set to "0.0.0.0". If "port"
156           is missing it will be set to 0.
157
158       family => 'inet6'
159           Will pack an IP address and port number from keys called "ip" and
160           "port".  If "ip" is missing it will be set to "::". If "port" is
161           missing it will be set to 0. Optionally will also include values
162           from "scopeid" and "flowinfo" keys if provided.
163
164           This will only work if a "pack_sockaddr_in6" function can be found
165           in "Socket"
166
167       family => 'unix'
168           Will pack a UNIX socket path from a key called "path".
169
170   make_addr_for_peer
171          $connectaddr = IO::Async::OS->make_addr_for_peer( $family, $listenaddr )
172
173       Given the "sockdomain" and "sockname" of a listening socket. creates an
174       address suitable to connect() to it.
175
176       This method will handle specially any "AF_INET" address bound to
177       "INADDR_ANY" or any "AF_INET6" address bound to "IN6ADDR_ANY", as some
178       OSes do not allow connect(2)ing to those and would instead insist on
179       receiving "INADDR_LOOPBACK" or "IN6ADDR_LOOPBACK" respectively.
180
181       This method is used by the "->connect( peer => $sock )" parameter of
182       handle and loop connect methods.
183

LOOP IMPLEMENTATION METHODS

185       The following methods are provided on "IO::Async::OS" because they are
186       likely to require OS-specific implementations, but are used by
187       IO::Async::Loop to implement its functionality. It can use the HASH
188       reference "$loop->{os}" to store other data it requires.
189
190   loop_watch_signal
191   loop_unwatch_signal
192          IO::Async::OS->loop_watch_signal( $loop, $signal, $code )
193
194          IO::Async::OS->loop_unwatch_signal( $loop, $signal )
195
196       Used to implement the "watch_signal" / "unwatch_signal" Loop pair.
197
198   potentially_open_fds
199          @fds = IO::Async::OS->potentially_open_fds
200
201       Returns a list of filedescriptors which might need closing. By default
202       this will return "0 .. _SC_OPEN_MAX". OS-specific subclasses may have a
203       better guess.
204

AUTHOR

206       Paul Evans <leonerd@leonerd.org.uk>
207
208
209
210perl v5.36.1                      2023-05-14                IO::Async::OS(3pm)
Impressum