Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IO::Pipely(3)	      User Contributed Perl Documentation	 IO::Pipely(3)

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

VERSION
       version 0.005

SYNOPSIS
       Please read DESCRIPTION for detailed semantics and caveats.

	 use IO::Pipely	qw(pipely socketpairly);

	 # Create a one-directional pipe() or pipe-like	thing
	 # the best conduit type available.

	 my ($read, $write) = pipely();

	 # Create a one-directional pipe-like thing using an
	 # INET	socket specifically.  Other types are available.

	 my ($read, $write) = pipely(type => 'inet');

	 # Create a bidirectional pipe-like thing using
	 # the best conduit type available.

	 my (
	   $side_a_read,  $side_b_read,
	   $side_a_write, $side_b_write,
	 ) = socketpairly();

	 # Create a bidirectional pipe-like thing using	an INET	socket
	 # specifically.

	 my (
	   $side_a_read,  $side_b_read,
	   $side_a_write, $side_b_write,
	 ) = socketpairly(type => 'inet');

DESCRIPTION
       Pipes are troublesome beasts because there are a	few different,
       incompatible ways to create them.  Not all platforms support all	ways,
       and some	platforms may have hidden difficulties like incomplete or
       buggy support.

       IO::Pipely provides a couple functions to portably create one- and two-
       way pipes and pipe-like socket pairs.  It acknowledges and works	around
       known platform issues so	you don't have to.

       On the other hand, it doesn't work around unknown issues, so please
       report any problems early and often.

       IO::Pipely currently understands	pipe(),	UNIX-domain socketpair() and
       regular IPv4 localhost sockets.	This covers every platform tested so
       far, but	it's hardly complete.  Please help support other mechanisms,
       such as INET-domain socketpair()	and IPv6 localhost sockets.

       IO::Pipely will use different kinds of pipes or sockets depending on
       the operating system's capabilities and the number of directions
       requested.  The autodetection may be overridden by specifying a
       particular pipe type.

   pipely
       pipely()	creates	a one-directional pipe() or socket.  It's modeled
       after Perl's built-in pipe() function, but it creates and returns
       handles rather than opening ones	given to it.

       On success, pipely() returns two	file handles, the first	to read	from
       the pipe, and the second	writes into the	pipe.  It returns nothing on
       failure.

	 use IO::Pipely	qw(pipely);
	 my ($a_read, $b_write)	= pipely();
	 die "pipely() failed: $!" unless $a_read;

       When given a choice, it will prefer to use leaner pipe()	calls instead
       of socketpair() and socket().

       pipely()'s choice can be	forced using an	optional named "type"
       parameter.  See "PIPE TYPES" for	the types that can be used.

	 my ($a_read, $b_write)	= pipely(
	   type	=> 'pipe',
	 );

       On most systems,	pipely() will prefer to	open a pipe() first.  It will
       fall back to a UNIX socketpair()	or two localhost Internet sockets, in
       that order.

       On Windows (ActiveState and Strawberry Perl), pipely() prefers two
       localhost Internet sockets.  It will fall back to socketpair() and
       pipe(), both of which will probably fail.

       Cygwin Perl prefers pipe() first, localhost Internet sockets, and then
       socketpair().  socketpair() has been known to have problems on Cygwin.

       MacPerl (MacOS 9	and earlier) has similar capaibilities to Windows.

   socketpairly
       socketpairly() creates a	two-directional	socket pair.  It's modeled
       after Perl's built-in socketpair(), but it creates and returns handles
       rather than opening ones	given to it.

       On success, socketpairly() returns four file handles, read and write
       for one end, and	read and write for the other.  On failure, it returns
       nothing.

	 use IO::Pipely	qw(socketpairly);
	 my ($a_read, $b_read, $a_write, $b_write) = socketpairly();
	 die "socketpairly() failed: $!" unless	$a_read;

       socketpairly() returns two extra	"writer" handles.  They	exist for the
       fallback	case where two pipe() calls are	needed instead of one socket
       pair.  The extra	handles	can be ignored whenever	pipe() will never be
       used.  For example:

	 use IO::Pipely	qw(socketpairly);
	 my ($side_a, $side_b) = socketpairly( type => 'socketpair' );
	 die "socketpairly() failed: $!" unless	$side_a;

       When given a choice, it will prefer bidirectional sockets instead of
       pipe() calls.

       socketpairly()'s	choice can be forced using an optional named "type"
       parameter.  See "PIPE TYPES" for	the types that can be used.  In	this
       example,	two unidirectional pipes wil be	used instead of	a more
       efficient pair of sockets:

	 my ($a_read, $a_write,	$b_read, $b_write) = pipely(
	   type	=> 'pipe',
	 );

       On most systems,	socketpairly() will try	to open	a UNIX socketpair()
       first.  It will then fall back to a pair	of localhost Internet sockets,
       and finally it will try a pair of pipe()	calls.

       On Windows (ActiveState and Strawberry Perl), socketpairly() prefers a
       pair of localhost Internet sockets first.  It will then fall back to a
       UNIX socketpair(), and finally a	couple of pipe() calls.	 The fallback
       options will probably fail, but the code	remains	hopeful.

       Cygwin Perl prefers localhost Internet sockets first, followed by a
       pair of pipe() calls, and finally a UNIX	socketpair().  Those who know
       may find	this counter-intuitive,	but it works around known issues in
       some versions of	Cygwin socketpair().

       MacPerl (MacOS 9	and earlier) has similar capaibilities to Windows.

   PIPE	TYPES
       IO::Pipely currently supports three types of pipe and socket.  Other
       types are possible, but these three cover all known uses	so far.
       Please ask (or send patches) if additional types	are needed.

       pipe

       Attempt to establish a one-way pipe using one pipe() filehandle pair (2
       file descriptors), or a two-way pipe-like connection using two pipe()
       pairs (4	file descriptors).

       IO::Pipely prefers to use pipe()	for one-way pipes and some form	of
       socket pair for two-way pipelike	things.

       socketpair

       Attempt to establish a one- or two-way pipelike connection using	a
       single socketpair() call.  This uses two	file descriptors regardless
       whether the connection is one- or two-way.

       IO::Pipely prefers socketpair() for two-way connections,	unless the
       current platform	has known issues with the socketpair() call.

       Socket pairs are	UNIX domain only for now.  INET	domain may be added if
       it improves compatibility on some platform, or if someone contributes
       the code.

       inet

       Attempt to establish a one- or two-way pipelike connection using
       localhost socket() calls.  This uses two	file descriptors regardless
       whether the connection is one- or two-way.

       Localhost INET domain sockets are a last	resort for platforms that
       don't support something better.	They are the least secure method of
       communication since tools like tcpdump and Wireshark can	tap into them.
       On the other hand, this makes them easiest to debug.

KNOWN ISSUES
       These are issues	known to the developers	at the time of this writing.
       Things change, so check back now	and then.

   Cygwin
       CygWin seems to have a problem with socketpair()	and exec().  When an
       exec'd process closes, any data on sockets created with socketpair() is
       not flushed.  From irc.perl.org channel #poe:

	 <dngnand>   Sounds like a lapse in cygwin's exec implementation.
		     It	works ok under Unix-ish	systems?
	 <jdeluise2> yes, it works perfectly
	 <jdeluise2> but, if we	just use POE::Pipe::TwoWay->new("pipe")
		     it	always works fine on cygwin
	 <jdeluise2> by	the way, it looks like the reason is that
		     POE::Pipe::OneWay works because it	tries to make a
		     pipe first	instead	of a socketpair
	 <jdeluise2> this socketpair problem seems like	a long-standing
		     one with cygwin, according	to searches on google,
		     but never been fixed.

   MacOS 9
       IO::Pipely supports MacOS 9 for historical reasons.  It's unclear
       whether anyone still uses MacPerl, but the support is cheap since pipes
       and sockets there have many of the same caveats as they do on Windows.

   Symbol::gensym
       IO::Pipely uses Symbol::gensym()	instead	of autovivifying file handles.
       The main	reasons	against	gensym() have been stylistic ones so far.
       Meanwhile, gensym() is compatible farther back than handle
       autovivification.

   Windows
       ActiveState and Strawberry Perl don't support pipe() or UNIX
       socketpair().  Localhost	Internet sockets are used for everything
       there, including	one-way	pipes.

       For one-way pipes, the unused socket directions are shut	down to	avoid
       sending data the	wrong way through them.	 Use socketpairly() instead.

BUGS
       The functions implemented here die outright upon	failure, requiring
       eval{} around their calls.

       The following conduit types are currently unsupported because nobody
       has needed them so far.	Please submit a	request	(and/or	a patch) if
       any of these is needed:

	 UNIX socket()
	 INET-domain socketpair()
	 IPv4-specific localhost sockets
	 IPv6-specific localhost sockets

AUTHOR & COPYRIGHT
       IO::Pipely is copyright 2000-2013 by Rocco Caputo.  All rights
       reserved.  IO::Pipely is	free software; you may redistribute it and/or
       modify it under the same	terms as Perl itself.

HISTORY
       IO::Pipely is a spin-off	of the POE project's portable pipes.  Earlier
       versions	of the code have been tested and used in production systems
       for over	a decade.

perl v5.24.1			  2013-08-12			 IO::Pipely(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | KNOWN ISSUES | BUGS | AUTHOR & COPYRIGHT | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=IO::Pipely&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help