---
name: readpipe
signature: 'readpipe EXPR'
signatures:
  - 'readpipe EXPR'
  - 'readpipe'
since: 5.0
status: documented
categories: ["Processes"]
---

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

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

# readpipe

Run a shell command and return its standard output.

`readpipe` hands `EXPR` to the shell, waits for the child to finish,
and returns whatever the child wrote to its standard output. It is the
named form of the [`qx`](qx) (backticks) operator — `` `cmd` `` and
`qx/cmd/` both compile down to `readpipe`. Reach for the named form
when you want the command in a variable, when you want to suppress
the double-quote interpolation [`qx`](qx) performs, or when you want to
read a captured command out of `@ARGV`. If `EXPR` is omitted,
[`$_`](../perlvar) is used.

## Synopsis

```perl
readpipe EXPR
readpipe
$out  = readpipe $cmd;
@rows = readpipe $cmd;
```

## What you get back

Context decides the shape:

- **Scalar context** — one string containing the entire captured
  output, newlines and all.
- **List context** — a list of records, split on [`$/`](../perlvar) (the input
  record separator, newline by default). The separator stays attached
  to each element unless you [`chomp`](chomp) it off.

[`$?`](../perlvar) is set to the child's wait status after the command finishes,
exactly as with [`system`](system). A non-zero [`$?`](../perlvar) is the usual signal
that the command failed — the return value alone cannot tell you, since
a failing command may still have written output (or nothing) before
exiting.

```perl
my $out = readpipe "uname -a";
die "uname failed: \$? = $?" if $?;
```

## Global state it touches

- [`$_`](../perlvar) — used as the command when `EXPR` is omitted.
- [`$/`](../perlvar) — controls how list-context output is split into records.
  Set it to `undef` to slurp the whole output into a single element,
  or to `""` for paragraph mode.
- [`$?`](../perlvar) — set to the child's wait status on return.
- [`$!`](../perlvar) — set if the shell itself could not be launched.
- `%ENV` — the shell inherits the current environment.

## Examples

Capture one line of output:

```perl
my $host = readpipe "hostname";
chomp $host;
print "running on $host\n";
```

Command held in a variable — the reason `readpipe` exists as a named
function. Backticks would still work here, but `readpipe` makes the
intent explicit and avoids the visual noise of nested quoting:

```perl
my $cmd = "ls -1 /etc";
my @entries = readpipe $cmd;
chomp @entries;
print scalar(@entries), " entries under /etc\n";
```

Slurp everything as one string by disabling record separation:

```perl
local $/;                               # slurp mode
my $log = readpipe "dmesg";
print length($log), " bytes of kernel log\n";
```

Paragraph mode — each element is one blank-line-separated block:

```perl
local $/ = "";
my @paragraphs = readpipe "cat README";
print scalar(@paragraphs), " paragraphs\n";
```

Check the exit status properly. The return value is output; success
lives in [`$?`](../perlvar):

```perl
my @files = readpipe "find . -name '*.tmp' 2>/dev/null";
if ($? == 0) {
    chomp @files;
    unlink @files;
} else {
    warn "find exited with status ", ($? >> 8), "\n";
}
```

Use [`$_`](../perlvar) as the command. Rarely the clearest form, but legal:

```perl
$_ = "date";
my $when = readpipe;                    # same as readpipe $_
```

## Edge cases

- **No interpolation protection.** `readpipe` interpolates its
  argument exactly like a double-quoted string — the same as [`qx`](qx).
  `readpipe "rm $path"` with `$path` coming from user input is a
  shell-injection hole. Quote the value, or better, switch to a
  list-form [`system`](system) / piped [`open`](open) and skip the shell
  entirely.
- **Standard error is not captured.** Only the child's standard
  output comes back. Redirect stderr in the command itself if you
  want it merged: `readpipe "cmd 2>&1"`.
- **Shell is mandatory.** Even a single-word `readpipe "true"` goes
  through `/bin/sh`, which means shell quoting, globbing, and
  environment-variable expansion all apply. No list form exists.
- **Large output buffers in memory.** The whole child output is read
  before `readpipe` returns. For a command that produces gigabytes,
  use a piped [`open`](open) and read incrementally instead.
- **Empty output, zero exit.** A successful command that writes
  nothing returns the empty string in scalar context and the empty
  list in list context. Distinguish "ran and said nothing" from
  "never ran" by checking [`$?`](../perlvar).
- **Child died on signal.** [`$?`](../perlvar) encodes both exit code and signal
  — mask with `$? & 127` to get the signal number, `$? >> 8` for
  the exit code.
- **Windows quoting rules.** `readpipe` hands the string to the
  platform shell; on Windows that is `cmd.exe`, whose quoting and
  redirection rules differ from POSIX. pperl is Linux-only, so this
  is only relevant when porting scripts in.

## Differences from upstream

Fully compatible with upstream Perl 5.42.

## See also

- [`qx`](qx) — the operator form; `` `cmd` `` and `qx/cmd/` are
  shorthand for `readpipe` and carry identical semantics
- [`system`](system) — run a command without capturing output; use when
  you only care about exit status
- [`exec`](exec) — replace the current process with the command; no
  return, no capture
- [`open`](open) — piped open (`open my $fh, "-|", @cmd`) streams the
  child's output line-by-line without buffering it all
- [`$?`](../perlvar) — child wait status set by every process-launch builtin
- [`$/`](../perlvar) — input record separator that splits list-context output