---
name: pipe
signature: 'pipe READHANDLE, WRITEHANDLE'
status: documented
categories: ["Processes"]
---

```{index} single: pipe; Perl built-in
```

*[Processes](../perlfunc-by-category)*

# pipe

Open a pair of connected filehandles — one for reading, one for writing.

`pipe` wraps the `pipe(2)` system call. It creates an unnamed,
unidirectional byte channel in the kernel and hands you two
filehandles: `READHANDLE`, from which bytes can be read, and
`WRITEHANDLE`, into which bytes can be written. Anything written to
`WRITEHANDLE` becomes available on `READHANDLE` in the same order.
The classic use is communication between a parent process and a
child produced by [`fork`](fork): one side writes, the other reads.

## Synopsis

```perl
pipe READHANDLE, WRITEHANDLE
```

## What you get back

True on success, false on failure (with [`$!`](../perlvar) set to the reason —
typically `EMFILE` or `ENFILE` when the process or system file-table
is full). Both handles are created as side effects on the arguments;
there is no "pipe object" return value.

On success you now hold **two** open file descriptors. Every
descriptor you create is a descriptor you must [`close`](close) —
especially the end each process does **not** use after a
[`fork`](fork) (see *Edge cases*).

## Global state it touches

- [`$!`](../perlvar) — set on failure to the `errno` from the underlying
  `pipe(2)` call.
- [`$|`](../perlvar) — **autoflush** on the write-side handle. `print` buffers
  through PerlIO, so without autoflush the reader may see nothing
  until the writer exits or the buffer fills. Set [`$|`](../perlvar) on the
  write handle (typically via [`select`](select)) before writing, or
  your protocol will deadlock.
- [`$^F`](../perlvar) — the **maximum system filehandle**. New descriptors
  with [`fileno`](fileno) greater than `$^F` (default `2`, i.e. above
  `STDERR`) have the close-on-exec flag set automatically, so they
  do not leak into programs started by [`exec`](exec). Lower `$^F`
  to keep the pipe open across [`exec`](exec); raise it, or dup onto
  a low-numbered fd, to force inheritance.

## Examples

A parent writes a line; a forked child reads it:

```perl
pipe my $reader, my $writer or die "pipe: $!";

my $pid = fork // die "fork: $!";
if ($pid == 0) {
    # child: reads only
    close $writer;
    my $line = <$reader>;
    print "child saw: $line";
    close $reader;
    exit 0;
}

# parent: writes only
close $reader;
$writer->autoflush(1);
print $writer "hello from parent\n";
close $writer;
waitpid $pid, 0;
```

The child reports the other direction — a child produces data, the
parent consumes it:

```perl
pipe my $reader, my $writer or die "pipe: $!";

my $pid = fork // die "fork: $!";
if ($pid == 0) {
    close $reader;
    $writer->autoflush(1);
    print $writer "$_\n" for 1 .. 5;
    close $writer;
    exit 0;
}

close $writer;
while (my $line = <$reader>) {
    print "got: $line";
}
close $reader;
waitpid $pid, 0;
```

Autoflush from the selected-handle side, for code that predates
`IO::Handle` method calls:

```perl
pipe my $reader, my $writer or die "pipe: $!";
my $old = select $writer; $| = 1; select $old;
```

For most uses, [`open`](open) with a pipe mode is simpler — it forks,
pipes, and `exec`s for you:

```perl
open my $fh, '|-', 'gzip', '-c' or die $!;   # write to gzip's stdin
print $fh "data\n";
close $fh;

open my $fh, '-|', 'ls', '-l'   or die $!;   # read from ls's stdout
while (my $line = <$fh>) { print $line }
close $fh;
```

Reach for bare `pipe` when you need both directions, need to retain
the unexec'd child, or are building something [`open`](open)'s two
pipe-forms do not cover — then `IPC::Open2` /
`IPC::Open3` wrap the `pipe` + [`fork`](fork) +
[`exec`](exec) dance for you.

## Edge cases

- **Close the end you do not use.** After [`fork`](fork), **both**
  processes hold **both** descriptors. The reader must close the
  write end, and the writer must close the read end. Skip this and
  you get the classic pipe bug: the reader's `<$reader>` never
  returns EOF, because the kernel still sees a writer open (the
  reader's own, idle, copy of `$writer`). The program hangs.
- **Writing to a reader-less pipe raises `SIGPIPE`.** Once every
  copy of the read end is closed, the next [`print`](print) on the
  write side delivers `SIGPIPE`, whose default action is to kill
  the process. Install `$SIG{PIPE} = 'IGNORE'` (or a handler) to
  turn it into a normal write failure with [`$!`](../perlvar) set to
  `EPIPE`, which you can then check.
- **Deadlock in pipe loops.** Two processes each writing to the
  other through pipes will block forever if both write buffers fill
  before either process reads. Kernel pipe buffers are small
  (typically 64 KiB). Drain one side, use non-blocking I/O, or use
  [`select`](select) / `IO::Select` to multiplex.
- **Buffering hides writes.** Without [`$|`](../perlvar) (or
  `$writer->autoflush(1)`) on the write side, data sits in PerlIO's
  buffer until the buffer fills or the handle is closed. A reader
  blocked on `<$reader>` will wait — often indefinitely — for data
  that has already been "written" from the writer's point of view.
- **Unidirectional only.** `pipe` produces a one-way channel: write
  to `WRITEHANDLE`, read from `READHANDLE`, not the reverse. For
  bidirectional communication use [`socketpair`](socketpair) or two
  pipes.
- **Binary data.** The handles returned by `pipe` start in the
  default PerlIO layer stack. If you are moving raw bytes across
  the pipe, apply `binmode` to both ends; otherwise CRLF or
  encoding layers inherited from the process defaults can rewrite
  your data.
- **Close-on-exec and [`fileno`](fileno).** On systems with
  `FD_CLOEXEC`, any new descriptor whose [`fileno`](fileno) exceeds
  [`$^F`](../perlvar) is created with the close-on-exec flag set. Pipe
  descriptors typically land well above `2`, so by default they do
  **not** survive [`exec`](exec) — which is normally what you want.
  Lower `$^F` *before* calling `pipe` if you intend to pass the
  descriptors to an `exec`'d program.

## Differences from upstream

Fully compatible with upstream Perl 5.42.

## See also

- [`fork`](fork) — the other half of the pipe idiom; `pipe` is
  almost always called just before a `fork`
- [`open`](open) — the `'|-'` and `'-|'` modes fork, pipe, and
  `exec` a child in one call; prefer them when you need exactly
  one direction to one external command
- [`close`](close) — closing the unused end in each process is
  mandatory, not optional
- [`read`](read) — byte-oriented reads from `READHANDLE` when the
  line-oriented `<$fh>` form is the wrong shape
- [`print`](print) — the normal way to push data into
  `WRITEHANDLE`; remember [`$|`](../perlvar)
- [`fileno`](fileno) — recover the underlying file descriptor, e.g.
  to hand to [`select`](select) / `IO::Select` or to a lower-level
  system call