1IO::Async::OS(3pm) User Contributed Perl Documentation IO::Async::OS(3pm)
2
6 "IO::Async::OS" - operating system abstractions for "IO::Async"
7
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 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 The following constants may be overridden by environment variables.
20 • HAVE_POSIX_FORK
22 True if the fork() call has full POSIX semantics (full process
24 separation). This is true on most OSes but false on MSWin32.
25 This may be overridden to be false by setting the environment
27 variable "IO_ASYNC_NO_FORK".
28 • HAVE_THREADS
30 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 This may be overridable to be false by setting the environment
36 variable "IO_ASYNC_NO_THREADS".
37 getfamilybyname
39 $family = IO::Async::OS->getfamilybyname( $name )
40 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 getsocktypebyname
47 $socktype = IO::Async::OS->getsocktypebyname( $name )
48 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 socketpair
54 ( $S1, $S2 ) = IO::Async::OS->socketpair( $family, $socktype, $proto )
55 An abstraction of the socketpair(2) syscall, where any argument may be
57 missing (or given as "undef").
58 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 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 $family and $socktype may also be given symbolically as defined by
69 "getfamilybyname" and "getsocktypebyname".
70 pipepair
72 ( $rd, $wr ) = IO::Async::OS->pipepair
73 An abstraction of the pipe(2) syscall, which returns the two new
75 handles.
76 pipequad
78 ( $rdA, $wrA, $rdB, $wrB ) = IO::Async::OS->pipequad
79 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 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 When creating a IO::Async::Stream or subclass of it, the "read_handle"
91 and "write_handle" parameters should always be used.
92 my ( $childRd, $myWr, $myRd, $childWr ) = IO::Async::OS->pipequad;
94 $loop->open_process(
96 stdin => $childRd,
97 stdout => $childWr,
98 ...
99 );
100 my $str = IO::Async::Stream->new(
102 read_handle => $myRd,
103 write_handle => $myWr,
104 ...
105 );
106 $loop->add( $str );
107 signame2num
109 $signum = IO::Async::OS->signame2num( $signame )
110 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 signum2name
117 $signame = IO::Async::OS->signum2name( $signum )
118 The inverse of signame2num; this method convers signal numbers into
120 readable names.
121 extract_addrinfo
123 ( $family, $socktype, $protocol, $addr ) = IO::Async::OS->extract_addrinfo( $ai )
124 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 If given an ARRAY it should be in the following form:
130 [ $family, $socktype, $protocol, $addr ]
132 If given a HASH it should contain the following keys:
134 family socktype protocol addr
136 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 The family type may also be given as a symbolic string as defined by
141 "getfamilybyname".
142 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 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 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 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 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 This will only work if a "pack_sockaddr_in6" function can be found
165 in "Socket"
166 family => 'unix'
168 Will pack a UNIX socket path from a key called "path".
169 make_addr_for_peer
171 $connectaddr = IO::Async::OS->make_addr_for_peer( $family, $listenaddr )
172 Given the "sockdomain" and "sockname" of a listening socket. creates an
174 address suitable to connect() to it.
175 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 This method is used by the "->connect( peer => $sock )" parameter of
182 handle and loop connect methods.
183
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 loop_watch_signal
191 loop_unwatch_signal
192 IO::Async::OS->loop_watch_signal( $loop, $signal, $code )
193 IO::Async::OS->loop_unwatch_signal( $loop, $signal )
195 Used to implement the "watch_signal" / "unwatch_signal" Loop pair.
197 potentially_open_fds
199 @fds = IO::Async::OS->potentially_open_fds
200 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
206 Paul Evans <leonerd@leonerd.org.uk>
207perl v5.36.1 2023-05-14 IO::Async::OS(3pm)