{
    "mode": "perldoc",
    "parameter": "IO::Pipely",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/IO%3A%3APipely/json",
    "generated": "2026-06-09T17:25:42Z",
    "synopsis": "Please read DESCRIPTION for detailed semantics and caveats.\nuse IO::Pipely qw(pipely socketpairly);\n# Create a one-directional pipe() or pipe-like thing\n# the best conduit type available.\nmy ($read, $write) = pipely();\n# Create a one-directional pipe-like thing using an\n# INET socket specifically.  Other types are available.\nmy ($read, $write) = pipely(type => 'inet');\n# Create a bidirectional pipe-like thing using\n# the best conduit type available.\nmy (\n$sidearead, $sideawrite,\n$sidebread, $sidebwrite,\n) = socketpairly();\n# Create a bidirectional pipe-like thing using an INET socket\n# specifically.\nmy (\n$sidearead, $sideawrite,\n$sidebread, $sidebwrite,\n) = socketpairly(type => 'inet');",
    "sections": {
        "NAME": {
            "content": "IO::Pipely - Portably create pipe() or pipe-like handles, one way or another.\n",
            "subsections": []
        },
        "VERSION": {
            "content": "version 0.006\n",
            "subsections": []
        },
        "SYNOPSIS": {
            "content": "Please read DESCRIPTION for detailed semantics and caveats.\n\nuse IO::Pipely qw(pipely socketpairly);\n\n# Create a one-directional pipe() or pipe-like thing\n# the best conduit type available.\n\nmy ($read, $write) = pipely();\n\n# Create a one-directional pipe-like thing using an\n# INET socket specifically.  Other types are available.\n\nmy ($read, $write) = pipely(type => 'inet');\n\n# Create a bidirectional pipe-like thing using\n# the best conduit type available.\n\nmy (\n$sidearead, $sideawrite,\n$sidebread, $sidebwrite,\n) = socketpairly();\n\n# Create a bidirectional pipe-like thing using an INET socket\n# specifically.\n\nmy (\n$sidearead, $sideawrite,\n$sidebread, $sidebwrite,\n) = socketpairly(type => 'inet');\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "Pipes are troublesome beasts because there are a few different, incompatible ways to create\nthem. Not all platforms support all ways, and some platforms may have hidden difficulties like\nincomplete or buggy support.\n\nIO::Pipely provides a couple functions to portably create one- and two-way pipes and pipe-like\nsocket pairs. It acknowledges and works around known platform issues so you don't have to.\n\nOn the other hand, it doesn't work around unknown issues, so please report any problems early\nand often.\n\nIO::Pipely currently understands pipe(), UNIX-domain socketpair() and regular IPv4 localhost\nsockets. This covers every platform tested so far, but it's hardly complete. Please help support\nother mechanisms, such as INET-domain socketpair() and IPv6 localhost sockets.\n\nIO::Pipely will use different kinds of pipes or sockets depending on the operating system's\ncapabilities and the number of directions requested. The autodetection may be overridden by\nspecifying a particular pipe type.\n\npipely",
            "subsections": [
                {
                    "name": "pipely",
                    "content": "function, but it creates and returns handles rather than opening ones given to it.\n\nOn success, pipely() returns two file handles, the first to read from the pipe, and the second\nwrites into the pipe. It returns nothing on failure.\n\nuse IO::Pipely qw(pipely);\nmy ($aread, $bwrite) = pipely();\ndie \"pipely() failed: $!\" unless $aread;\n\nWhen given a choice, it will prefer to use leaner pipe() calls instead of socketpair() and"
                },
                {
                    "name": "socket",
                    "content": ""
                },
                {
                    "name": "pipely",
                    "content": "the types that can be used.\n\nmy ($aread, $bwrite) = pipely(\ntype => 'pipe',\n);\n\nOn most systems, pipely() will prefer to open a pipe() first. It will fall back to a UNIX"
                },
                {
                    "name": "socketpair",
                    "content": "On Windows (ActiveState and Strawberry Perl), pipely() prefers two localhost Internet sockets.\nIt will fall back to socketpair() and pipe(), both of which will probably fail.\n\nCygwin Perl prefers pipe() first, localhost Internet sockets, and then socketpair()."
                },
                {
                    "name": "socketpair",
                    "content": "MacPerl (MacOS 9 and earlier) has similar capaibilities to Windows.\n\nsocketpairly"
                },
                {
                    "name": "socketpairly",
                    "content": ""
                },
                {
                    "name": "socketpair",
                    "content": "On success, socketpairly() returns four file handles, read and write for one end, and read and\nwrite for the other. On failure, it returns nothing.\n\nuse IO::Pipely qw(socketpairly);\nmy ($aread, $awrite, $bread, $bwrite) = socketpairly();\ndie \"socketpairly() failed: $!\" unless $aread;\n"
                },
                {
                    "name": "socketpairly",
                    "content": ""
                },
                {
                    "name": "pipe",
                    "content": ""
                },
                {
                    "name": "pipe",
                    "content": "use IO::Pipely qw(socketpairly);\nmy ($sidea, undef, $sideb, undef) = socketpairly( type => 'socketpair' );\ndie \"socketpairly() failed: $!\" unless $sidea;\n\nWhen given a choice, it will prefer bidirectional sockets instead of pipe() calls.\n"
                },
                {
                    "name": "socketpairly",
                    "content": "for the types that can be used. In this example, two unidirectional pipes wil be used instead of\na more efficient pair of sockets:\n\nmy ($aread, $awrite, $bread, $bwrite) = socketpairly(\ntype => 'pipe',\n);\n\nOn most systems, socketpairly() will try to open a UNIX socketpair() first. It will then fall\nback to a pair of localhost Internet sockets, and finally it will try a pair of pipe() calls.\n\nOn Windows (ActiveState and Strawberry Perl), socketpairly() prefers a pair of localhost\nInternet sockets first. It will then fall back to a UNIX socketpair(), and finally a couple of"
                },
                {
                    "name": "pipe",
                    "content": "Cygwin Perl prefers localhost Internet sockets first, followed by a pair of pipe() calls, and\nfinally a UNIX socketpair(). Those who know may find this counter-intuitive, but it works around\nknown issues in some versions of Cygwin socketpair().\n\nMacPerl (MacOS 9 and earlier) has similar capaibilities to Windows.\n\nPIPE TYPES\nIO::Pipely currently supports three types of pipe and socket. Other types are possible, but\nthese three cover all known uses so far. Please ask (or send patches) if additional types are\nneeded.\n\npipe\nAttempt to establish a one-way pipe using one pipe() filehandle pair (2 file descriptors), or a\ntwo-way pipe-like connection using two pipe() pairs (4 file descriptors).\n\nIO::Pipely prefers to use pipe() for one-way pipes and some form of socket pair for two-way\npipelike things.\n\nsocketpair\nAttempt to establish a one- or two-way pipelike connection using a single socketpair() call.\nThis uses two file descriptors regardless whether the connection is one- or two-way.\n\nIO::Pipely prefers socketpair() for two-way connections, unless the current platform has known\nissues with the socketpair() call.\n\nSocket pairs are UNIX domain only for now. INET domain may be added if it improves compatibility\non some platform, or if someone contributes the code.\n\ninet\nAttempt to establish a one- or two-way pipelike connection using localhost socket() calls. This\nuses two file descriptors regardless whether the connection is one- or two-way.\n\nLocalhost INET domain sockets are a last resort for platforms that don't support something\nbetter. They are the least secure method of communication since tools like tcpdump and Wireshark\ncan tap into them. On the other hand, this makes them easiest to debug.\n"
                }
            ]
        },
        "KNOWN ISSUES": {
            "content": "These are issues known to the developers at the time of this writing. Things change, so check\nback now and then.\n",
            "subsections": [
                {
                    "name": "Cygwin",
                    "content": "CygWin seems to have a problem with socketpair() and exec(). When an exec'd process closes, any\ndata on sockets created with socketpair() is not flushed. From irc.perl.org channel #poe:\n\n<dngnand>   Sounds like a lapse in cygwin's exec implementation.\nIt works ok under Unix-ish systems?\n<jdeluise2> yes, it works perfectly\n<jdeluise2> but, if we just use POE::Pipe::TwoWay->new(\"pipe\")\nit always works fine on cygwin\n<jdeluise2> by the way, it looks like the reason is that\nPOE::Pipe::OneWay works because it tries to make a\npipe first instead of a socketpair\n<jdeluise2> this socketpair problem seems like a long-standing\none with cygwin, according to searches on google,\nbut never been fixed.\n"
                },
                {
                    "name": "MacOS 9",
                    "content": "IO::Pipely supports MacOS 9 for historical reasons. It's unclear whether anyone still uses\nMacPerl, but the support is cheap since pipes and sockets there have many of the same caveats as\nthey do on Windows.\n"
                },
                {
                    "name": "Symbol::gensym",
                    "content": "IO::Pipely uses Symbol::gensym() instead of autovivifying file handles. The main reasons against"
                },
                {
                    "name": "gensym",
                    "content": "handle autovivification.\n"
                },
                {
                    "name": "Windows",
                    "content": "ActiveState and Strawberry Perl don't support pipe() or UNIX socketpair(). Localhost Internet\nsockets are used for everything there, including one-way pipes.\n\nFor one-way pipes, the unused socket directions are shut down to avoid sending data the wrong\nway through them. Use socketpairly() instead.\n"
                }
            ]
        },
        "BUGS": {
            "content": "The functions implemented here die outright upon failure, requiring eval{} around their calls.\n\nThe following conduit types are currently unsupported because nobody has needed them so far.\nPlease submit a request (and/or a patch) if any of these is needed:\n\nUNIX socket()\nINET-domain socketpair()\nIPv4-specific localhost sockets\nIPv6-specific localhost sockets\n\nAUTHOR & COPYRIGHT\nIO::Pipely is copyright 2000-2021 by Rocco Caputo. All rights reserved. IO::Pipely is free\nsoftware; you may redistribute it and/or modify it under the same terms as Perl itself.\n",
            "subsections": []
        },
        "HISTORY": {
            "content": "IO::Pipely is a spin-off of the POE project's portable pipes. Earlier versions of the code have\nbeen tested and used in production systems for over a decade.\n",
            "subsections": []
        }
    },
    "summary": "IO::Pipely - Portably create pipe() or pipe-like handles, one way or another.",
    "flags": [],
    "examples": [],
    "see_also": []
}