# NAME

Sys::Pipe - `pipe2()` in Perl

# SYNOPSIS

    use Fcntl;
    use Sys::Pipe;

    Sys::Pipe::pipe( my $r, my $w, O_NONBLOCK ) or die "pipe: $!";

# DESCRIPTION

Ever wish you could create a pipe that starts out non-blocking?
Linux and a number of other OSes can do this via a proprietary `pipe2()`
system call; this little library exposes that functionality to Perl.

# WHEN IS THIS USEFUL?

As shown above, this exposes the ability to create a pipe that starts
out non-blocking. If that’s all you need, then the gain here is mostly just
tidiness. It _is_ also faster than doing:

    pipe my $r, my $w or die "pipe: $!";
    $r->blocking(0);
    $w->blocking(0);

… but the above is already quite fast, so that may not make a real-world
difference for you.

In Linux, this also exposes the ability to create a “packet mode” pipe.
Other OSes may allow similar and/or other functionality. See your
system’s [pipe2(2)](http://man.he.net/man2/pipe2) for more details.

# STATUS

This module is best considered **EXPERIMENTAL**. If you find a problem,
please file a bug report. Thank you!

# SEE ALSO

Perl’s [socket()](https://metacpan.org/pod/perlfunc#socket-SOCKET-DOMAIN-TYPE-PROTOCOL)
built-in allows similar functionality on the relevant OSes, e.g.:

    use Socket;

    socket( my $s, AF_INET, SOCK_STREAM | SOCK_NONBLOCK, 0 ) or do {
        die "socket(): $!";
    };

# FUNCTIONS

## $success\_yn = pipe( READHANDLE, WRITEHANDLE \[, FLAGS\] )

A drop-in replacement for Perl’s `pipe()` built-in that optionally
accepts a numeric _FLAGS_ argument. See your system’s [pipe2(2)](http://man.he.net/man2/pipe2)
documentation for what values you can pass in there.

Note that behavior is currently **undefined** if _FLAGS_ is nonzero on
any system (e.g., macOS) that lacks `pipe2()`. (As of this writing an
exception is thrown; that may change eventually.)

## $yn = has\_pipe2()

Returns a boolean that indicates whether the underlying system can
implement `pipe2()` mechanics.

# COPYRIGHT

Copyright 2020 Gasper Software Consulting. All rights reserved.