1IO::Async::OS(3) User Contributed Perl Documentation IO::Async::OS(3)
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 extract_addrinfo
117 ( $family, $socktype, $protocol, $addr ) = IO::Async::OS->extract_addrinfo( $ai )
118 Given an ARRAY or HASH reference value containing an addrinfo, returns
120 a family, socktype and protocol argument suitable for a "socket" call
121 and an address suitable for "connect" or "bind".
122 If given an ARRAY it should be in the following form:
124 [ $family, $socktype, $protocol, $addr ]
126 If given a HASH it should contain the following keys:
128 family socktype protocol addr
130 Each field in the result will be initialised to 0 (or empty string for
132 the address) if not defined in the $ai value.
133 The family type may also be given as a symbolic string as defined by
135 "getfamilybyname".
136 The socktype may also be given as a symbolic string; "stream", "dgram"
138 or "raw"; this will be converted to the appropriate "SOCK_*" constant.
139 Note that the "addr" field, if provided, must be a packed socket
141 address, such as returned by "pack_sockaddr_in" or "pack_sockaddr_un".
142 If the HASH form is used, rather than passing a packed socket address
144 in the "addr" field, certain other hash keys may be used instead for
145 convenience on certain named families.
146 family => 'inet'
148 Will pack an IP address and port number from keys called "ip" and
149 "port". If "ip" is missing it will be set to "0.0.0.0". If "port"
150 is missing it will be set to 0.
151 family => 'inet6'
153 Will pack an IP address and port number from keys called "ip" and
154 "port". If "ip" is missing it will be set to "::". If "port" is
155 missing it will be set to 0. Optionally will also include values
156 from "scopeid" and "flowinfo" keys if provided.
157 This will only work if a "pack_sockaddr_in6" function can be found
159 in "Socket"
160 family => 'unix'
162 Will pack a UNIX socket path from a key called "path".
163
165 The following methods are provided on "IO::Async::OS" because they are
166 likely to require OS-specific implementations, but are used by
167 IO::Async::Loop to implement its functionality. It can use the HASH
168 reference "$loop->{os}" to store other data it requires.
169 loop_watch_signal
171 loop_unwatch_signal
172 IO::Async::OS->loop_watch_signal( $loop, $signal, $code )
173 IO::Async::OS->loop_unwatch_signal( $loop, $signal )
175 Used to implement the "watch_signal" / "unwatch_signal" Loop pair.
177 potentially_open_fds
179 @fds = IO::Async::OS->potentially_open_fds
180 Returns a list of filedescriptors which might need closing. By default
182 this will return "0 .. _SC_OPEN_MAX". OS-specific subclasses may have a
183 better guess.
184
186 Paul Evans <leonerd@leonerd.org.uk>
187perl v5.32.0 2020-09-24 IO::Async::OS(3)