1IO::Pipely(3) User Contributed Perl Documentation IO::Pipely(3)
2
6 IO::Pipely - Portably create pipe() or pipe-like handles, one way or
7 another.
8
10 version 0.006
11
13 Please read DESCRIPTION for detailed semantics and caveats.
14 use IO::Pipely qw(pipely socketpairly);
16 # Create a one-directional pipe() or pipe-like thing
18 # the best conduit type available.
19 my ($read, $write) = pipely();
21 # Create a one-directional pipe-like thing using an
23 # INET socket specifically. Other types are available.
24 my ($read, $write) = pipely(type => 'inet');
26 # Create a bidirectional pipe-like thing using
28 # the best conduit type available.
29 my (
31 $side_a_read, $side_a_write,
32 $side_b_read, $side_b_write,
33 ) = socketpairly();
34 # Create a bidirectional pipe-like thing using an INET socket
36 # specifically.
37 my (
39 $side_a_read, $side_a_write,
40 $side_b_read, $side_b_write,
41 ) = socketpairly(type => 'inet');
42
44 Pipes are troublesome beasts because there are a few different,
45 incompatible ways to create them. Not all platforms support all ways,
46 and some platforms may have hidden difficulties like incomplete or
47 buggy support.
48 IO::Pipely provides a couple functions to portably create one- and two-
50 way pipes and pipe-like socket pairs. It acknowledges and works around
51 known platform issues so you don't have to.
52 On the other hand, it doesn't work around unknown issues, so please
54 report any problems early and often.
55 IO::Pipely currently understands pipe(), UNIX-domain socketpair() and
57 regular IPv4 localhost sockets. This covers every platform tested so
58 far, but it's hardly complete. Please help support other mechanisms,
59 such as INET-domain socketpair() and IPv6 localhost sockets.
60 IO::Pipely will use different kinds of pipes or sockets depending on
62 the operating system's capabilities and the number of directions
63 requested. The autodetection may be overridden by specifying a
64 particular pipe type.
65 pipely
67 pipely() creates a one-directional pipe() or socket. It's modeled
68 after Perl's built-in pipe() function, but it creates and returns
69 handles rather than opening ones given to it.
70 On success, pipely() returns two file handles, the first to read from
72 the pipe, and the second writes into the pipe. It returns nothing on
73 failure.
74 use IO::Pipely qw(pipely);
76 my ($a_read, $b_write) = pipely();
77 die "pipely() failed: $!" unless $a_read;
78 When given a choice, it will prefer to use leaner pipe() calls instead
80 of socketpair() and socket().
81 pipely()'s choice can be forced using an optional named "type"
83 parameter. See "PIPE TYPES" for the types that can be used.
84 my ($a_read, $b_write) = pipely(
86 type => 'pipe',
87 );
88 On most systems, pipely() will prefer to open a pipe() first. It will
90 fall back to a UNIX socketpair() or two localhost Internet sockets, in
91 that order.
92 On Windows (ActiveState and Strawberry Perl), pipely() prefers two
94 localhost Internet sockets. It will fall back to socketpair() and
95 pipe(), both of which will probably fail.
96 Cygwin Perl prefers pipe() first, localhost Internet sockets, and then
98 socketpair(). socketpair() has been known to have problems on Cygwin.
99 MacPerl (MacOS 9 and earlier) has similar capaibilities to Windows.
101 socketpairly
103 socketpairly() creates a two-directional socket pair. It's modeled
104 after Perl's built-in socketpair(), but it creates and returns handles
105 rather than opening ones given to it.
106 On success, socketpairly() returns four file handles, read and write
108 for one end, and read and write for the other. On failure, it returns
109 nothing.
110 use IO::Pipely qw(socketpairly);
112 my ($a_read, $a_write, $b_read, $b_write) = socketpairly();
113 die "socketpairly() failed: $!" unless $a_read;
114 socketpairly() returns two extra "writer" handles. They exist for the
116 fallback case where two pipe() calls are needed instead of one socket
117 pair. The extra handles can be ignored whenever pipe() will never be
118 used. For example:
119 use IO::Pipely qw(socketpairly);
121 my ($side_a, undef, $side_b, undef) = socketpairly( type => 'socketpair' );
122 die "socketpairly() failed: $!" unless $side_a;
123 When given a choice, it will prefer bidirectional sockets instead of
125 pipe() calls.
126 socketpairly()'s choice can be forced using an optional named "type"
128 parameter. See "PIPE TYPES" for the types that can be used. In this
129 example, two unidirectional pipes wil be used instead of a more
130 efficient pair of sockets:
131 my ($a_read, $a_write, $b_read, $b_write) = socketpairly(
133 type => 'pipe',
134 );
135 On most systems, socketpairly() will try to open a UNIX socketpair()
137 first. It will then fall back to a pair of localhost Internet sockets,
138 and finally it will try a pair of pipe() calls.
139 On Windows (ActiveState and Strawberry Perl), socketpairly() prefers a
141 pair of localhost Internet sockets first. It will then fall back to a
142 UNIX socketpair(), and finally a couple of pipe() calls. The fallback
143 options will probably fail, but the code remains hopeful.
144 Cygwin Perl prefers localhost Internet sockets first, followed by a
146 pair of pipe() calls, and finally a UNIX socketpair(). Those who know
147 may find this counter-intuitive, but it works around known issues in
148 some versions of Cygwin socketpair().
149 MacPerl (MacOS 9 and earlier) has similar capaibilities to Windows.
151 PIPE TYPES
153 IO::Pipely currently supports three types of pipe and socket. Other
154 types are possible, but these three cover all known uses so far.
155 Please ask (or send patches) if additional types are needed.
156 pipe
158 Attempt to establish a one-way pipe using one pipe() filehandle pair (2
160 file descriptors), or a two-way pipe-like connection using two pipe()
161 pairs (4 file descriptors).
162 IO::Pipely prefers to use pipe() for one-way pipes and some form of
164 socket pair for two-way pipelike things.
165 socketpair
167 Attempt to establish a one- or two-way pipelike connection using a
169 single socketpair() call. This uses two file descriptors regardless
170 whether the connection is one- or two-way.
171 IO::Pipely prefers socketpair() for two-way connections, unless the
173 current platform has known issues with the socketpair() call.
174 Socket pairs are UNIX domain only for now. INET domain may be added if
176 it improves compatibility on some platform, or if someone contributes
177 the code.
178 inet
180 Attempt to establish a one- or two-way pipelike connection using
182 localhost socket() calls. This uses two file descriptors regardless
183 whether the connection is one- or two-way.
184 Localhost INET domain sockets are a last resort for platforms that
186 don't support something better. They are the least secure method of
187 communication since tools like tcpdump and Wireshark can tap into them.
188 On the other hand, this makes them easiest to debug.
189
191 These are issues known to the developers at the time of this writing.
192 Things change, so check back now and then.
193 Cygwin
195 CygWin seems to have a problem with socketpair() and exec(). When an
196 exec'd process closes, any data on sockets created with socketpair() is
197 not flushed. From irc.perl.org channel #poe:
198 <dngnand> Sounds like a lapse in cygwin's exec implementation.
200 It works ok under Unix-ish systems?
201 <jdeluise2> yes, it works perfectly
202 <jdeluise2> but, if we just use POE::Pipe::TwoWay->new("pipe")
203 it always works fine on cygwin
204 <jdeluise2> by the way, it looks like the reason is that
205 POE::Pipe::OneWay works because it tries to make a
206 pipe first instead of a socketpair
207 <jdeluise2> this socketpair problem seems like a long-standing
208 one with cygwin, according to searches on google,
209 but never been fixed.
210 MacOS 9
212 IO::Pipely supports MacOS 9 for historical reasons. It's unclear
213 whether anyone still uses MacPerl, but the support is cheap since pipes
214 and sockets there have many of the same caveats as they do on Windows.
215 Symbol::gensym
217 IO::Pipely uses Symbol::gensym() instead of autovivifying file handles.
218 The main reasons against gensym() have been stylistic ones so far.
219 Meanwhile, gensym() is compatible farther back than handle
220 autovivification.
221 Windows
223 ActiveState and Strawberry Perl don't support pipe() or UNIX
224 socketpair(). Localhost Internet sockets are used for everything
225 there, including one-way pipes.
226 For one-way pipes, the unused socket directions are shut down to avoid
228 sending data the wrong way through them. Use socketpairly() instead.
229
231 The functions implemented here die outright upon failure, requiring
232 eval{} around their calls.
233 The following conduit types are currently unsupported because nobody
235 has needed them so far. Please submit a request (and/or a patch) if
236 any of these is needed:
237 UNIX socket()
239 INET-domain socketpair()
240 IPv4-specific localhost sockets
241 IPv6-specific localhost sockets
242
244 IO::Pipely is copyright 2000-2021 by Rocco Caputo. All rights
245 reserved. IO::Pipely is free software; you may redistribute it and/or
246 modify it under the same terms as Perl itself.
247
249 IO::Pipely is a spin-off of the POE project's portable pipes. Earlier
250 versions of the code have been tested and used in production systems
251 for over a decade.
252perl v5.34.0 2022-01-21 IO::Pipely(3)