1IO::Pipely(3)         User Contributed Perl Documentation        IO::Pipely(3)
2
3
4

NAME

6       IO::Pipely - Portably create pipe() or pipe-like handles, one way or
7       another.
8

VERSION

10       version 0.006
11

SYNOPSIS

13       Please read DESCRIPTION for detailed semantics and caveats.
14
15         use IO::Pipely qw(pipely socketpairly);
16
17         # Create a one-directional pipe() or pipe-like thing
18         # the best conduit type available.
19
20         my ($read, $write) = pipely();
21
22         # Create a one-directional pipe-like thing using an
23         # INET socket specifically.  Other types are available.
24
25         my ($read, $write) = pipely(type => 'inet');
26
27         # Create a bidirectional pipe-like thing using
28         # the best conduit type available.
29
30         my (
31           $side_a_read, $side_a_write,
32           $side_b_read, $side_b_write,
33         ) = socketpairly();
34
35         # Create a bidirectional pipe-like thing using an INET socket
36         # specifically.
37
38         my (
39           $side_a_read, $side_a_write,
40           $side_b_read, $side_b_write,
41         ) = socketpairly(type => 'inet');
42

DESCRIPTION

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
49       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
53       On the other hand, it doesn't work around unknown issues, so please
54       report any problems early and often.
55
56       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
61       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
66   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
71       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
75         use IO::Pipely qw(pipely);
76         my ($a_read, $b_write) = pipely();
77         die "pipely() failed: $!" unless $a_read;
78
79       When given a choice, it will prefer to use leaner pipe() calls instead
80       of socketpair() and socket().
81
82       pipely()'s choice can be forced using an optional named "type"
83       parameter.  See "PIPE TYPES" for the types that can be used.
84
85         my ($a_read, $b_write) = pipely(
86           type => 'pipe',
87         );
88
89       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
93       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
97       Cygwin Perl prefers pipe() first, localhost Internet sockets, and then
98       socketpair().  socketpair() has been known to have problems on Cygwin.
99
100       MacPerl (MacOS 9 and earlier) has similar capaibilities to Windows.
101
102   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
107       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
111         use IO::Pipely qw(socketpairly);
112         my ($a_read, $a_write, $b_read, $b_write) = socketpairly();
113         die "socketpairly() failed: $!" unless $a_read;
114
115       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
120         use IO::Pipely qw(socketpairly);
121         my ($side_a, undef, $side_b, undef) = socketpairly( type => 'socketpair' );
122         die "socketpairly() failed: $!" unless $side_a;
123
124       When given a choice, it will prefer bidirectional sockets instead of
125       pipe() calls.
126
127       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
132         my ($a_read, $a_write, $b_read, $b_write) = socketpairly(
133           type => 'pipe',
134         );
135
136       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
140       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
145       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
150       MacPerl (MacOS 9 and earlier) has similar capaibilities to Windows.
151
152   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
157       pipe
158
159       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
163       IO::Pipely prefers to use pipe() for one-way pipes and some form of
164       socket pair for two-way pipelike things.
165
166       socketpair
167
168       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
172       IO::Pipely prefers socketpair() for two-way connections, unless the
173       current platform has known issues with the socketpair() call.
174
175       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
179       inet
180
181       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
185       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

KNOWN ISSUES

191       These are issues known to the developers at the time of this writing.
192       Things change, so check back now and then.
193
194   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
199         <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
211   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
216   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
222   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
227       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

BUGS

231       The functions implemented here die outright upon failure, requiring
232       eval{} around their calls.
233
234       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
238         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

HISTORY

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.
252
253
254
255perl v5.34.0                      2022-01-21                     IO::Pipely(3)
Impressum