1IO::Async::OS(3)      User Contributed Perl Documentation     IO::Async::OS(3)
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   extract_addrinfo
117          ( $family, $socktype, $protocol, $addr ) = IO::Async::OS->extract_addrinfo( $ai )
118
119       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
123       If given an ARRAY it should be in the following form:
124
125        [ $family, $socktype, $protocol, $addr ]
126
127       If given a HASH it should contain the following keys:
128
129        family socktype protocol addr
130
131       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
134       The family type may also be given as a symbolic string as defined by
135       "getfamilybyname".
136
137       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
140       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
143       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
147       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
152       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
158           This will only work if a "pack_sockaddr_in6" function can be found
159           in "Socket"
160
161       family => 'unix'
162           Will pack a UNIX socket path from a key called "path".
163

LOOP IMPLEMENTATION METHODS

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
170   loop_watch_signal
171   loop_unwatch_signal
172          IO::Async::OS->loop_watch_signal( $loop, $signal, $code )
173
174          IO::Async::OS->loop_unwatch_signal( $loop, $signal )
175
176       Used to implement the "watch_signal" / "unwatch_signal" Loop pair.
177
178   potentially_open_fds
179          @fds = IO::Async::OS->potentially_open_fds
180
181       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

AUTHOR

186       Paul Evans <leonerd@leonerd.org.uk>
187
188
189
190perl v5.32.0                      2020-09-24                  IO::Async::OS(3)
Impressum