---
name: readline
signature: 'readline EXPR'
since: 5.0
status: documented
categories: ["I/O"]
---

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

*[I/O](../perlfunc-by-category)*

# readline

Read one or more records from a filehandle.

`readline` is the input primitive behind the `<FH>` diamond operator.
It reads from the filehandle named by `EXPR` (a typeglob, a glob
reference, or an `IO::Handle`), using the current value of [`$/`](../perlvar) to
decide where one record ends. If `EXPR` is omitted, `*ARGV` is read.
In scalar context it returns the next record; in list context it
returns every remaining record. End-of-file is signalled by [`undef`](undef)
(scalar) or an empty list.

## Synopsis

```perl
my $line  = readline $fh;       # one record, scalar context
my @all   = readline $fh;       # every remaining record
my $line  = <$fh>;              # same as scalar readline $fh
my @all   = <$fh>;              # same as list  readline $fh
readline;                       # reads from *ARGV
```

## What you get back

- **Scalar context**: the next record as a string, or [`undef`](undef) at
  end-of-file or on error. The record includes its terminator (the
  current [`$/`](../perlvar)) unless the last record in the file is missing one.
  After the returned value, [`$.`](../perlvar) is incremented — see the section on
  global state below.
- **List context**: a list of every remaining record until
  end-of-file. An empty list means the handle was already at EOF.
- **Slurp mode on an empty file**: when [`$/`](../perlvar) is [`undef`](undef) and context
  is scalar, the first call on a zero-byte handle returns `''`
  (empty string, defined); the next call returns [`undef`](undef). This lets
  `defined($slurp = readline $fh)` distinguish an empty file from a
  missing one without a separate `-s` test.

## Global state it touches

- [`$/`](../perlvar) — input record separator. Controls what counts as "one
  record". Default is `"\n"`. Special values are covered under
  *Record modes* below. Also known as `$INPUT_RECORD_SEPARATOR` or
  [`$RS`](../perlvar) under `use English`.
- [`$.`](../perlvar) — current input line number of the last handle read. `readline`
  increments [`$.`](../perlvar) once per record returned. [`$.`](../perlvar) is reset when the
  handle is explicitly [`close`](close)d, but **not** when `*ARGV` rolls from
  one file to the next — that continues counting across the whole
  input. Also `$INPUT_LINE_NUMBER` or `$NR` under `use English`.
- [`$_`](../perlvar) — the default scalar. When a `readline` call (or its `<FH>`
  equivalent) is used **as the condition of a `while` or `for`
  loop**, Perl implicitly assigns the result to [`$_`](../perlvar) and tests
  [`defined`](defined), not truth. `while (<$fh>) { ... }` is therefore safe on
  lines containing `"0"` or `""`.
- [`$!`](../perlvar) — errno. On a read error, `readline` returns [`undef`](undef) (scalar)
  or a truncated list, and sets [`$!`](../perlvar) to the operating-system error.
- `@ARGV` — when `EXPR` is omitted (or the handle is `ARGV`), each
  end-of-file causes Perl to [`open`](open) the next filename from `@ARGV`
  and continue reading. An empty `@ARGV` makes `ARGV` read `STDIN`.

## Record modes

[`$/`](../perlvar) selects one of four reading modes:

- **Line mode** (default) — [`$/`](../perlvar) is a non-empty string. A record
  ends at the next occurrence of that string. With the default
  `"\n"`, one call returns one line including its newline.
- **Paragraph mode** — `$/ = ""`. A record ends at the next run of
  two or more consecutive newlines. Leading blank lines before the
  first paragraph are skipped; the terminating blank line(s) are
  included in the returned string. Use `local $/ = ""` to confine
  the change to a block.
- **Slurp mode** — `$/ = undef`. The first call returns the entire
  remaining contents of the handle as one string; the next call
  returns [`undef`](undef). On an empty file, see the special case under
  *What you get back*.
- **Fixed-record mode** — `$/ = \N` (a reference to a positive
  integer) or `$/ = \"N"`. Each call reads exactly `N` bytes, or
  fewer at end-of-file. Useful for binary framing. The result is
  still counted as one record for [`$.`](../perlvar).

Changes to [`$/`](../perlvar) take effect on the next `readline` call. Scope them
with [`local`](local) so a subroutine does not silently change the caller's
idea of "line".

## Examples

Idiomatic line-by-line read. The `while` condition implicitly
assigns to [`$_`](../perlvar) and tests [`defined`](defined):

```perl
open my $fh, "<", "input.txt" or die "open: $!";
while (<$fh>) {
    chomp;
    print "line $.: $_\n";
}
close $fh;
```

Explicit `readline` with error detection. [`eof`](eof) must be checked
separately from the return value, because a legitimate line can be
the empty string:

```perl
while ( ! eof($fh) ) {
    defined( my $line = readline $fh )
        or die "readline failed: $!";
    # ... process $line ...
}
```

Slurp a whole file into a scalar:

```perl
my $contents = do {
    local $/;                   # undef — slurp mode
    open my $fh, "<", $path or die "open $path: $!";
    readline $fh;
};
```

Paragraph mode — read an RFC-822-style message header block:

```perl
open my $fh, "<", "message.eml" or die $!;
local $/ = "";
my $headers = <$fh>;            # up to the first blank line
my $body    = do { local $/; <$fh> };
```

Fixed-record mode — read 512-byte blocks from a device file:

```perl
open my $fh, "<:raw", "/dev/sda" or die $!;
local $/ = \512;
while (defined(my $block = <$fh>)) {
    last if length($block) < 512;   # short read at EOF
    # ... process $block ...
}
```

List context — pull every remaining line at once. Cheap for small
files, ruinous for large ones:

```perl
open my $fh, "<", "hosts" or die $!;
my @lines = <$fh>;              # every line, including terminators
chomp @lines;
```

Reading from `*ARGV` with no explicit handle — the classic Perl
filter idiom. `@ARGV` is consumed as a list of filenames, or
`STDIN` is read if `@ARGV` is empty:

```perl
while (defined(my $line = readline)) {
    print $line;                # cat(1) in one line
}
```

## Edge cases

- **EOF vs. error**: scalar `readline` returns [`undef`](undef) for both. Call
  `eof($fh)` or check [`$!`](../perlvar) to distinguish them. Inside `while (<$fh>)`
  the loop exits on either; add an explicit [`defined`](defined) plus [`$!`](../perlvar) check
  when you need to tell them apart.
- **A file with no trailing newline**: the last record is returned
  without a terminator in line mode. [`chomp`](chomp) is a no-op on such a
  value, which is the correct behaviour.
- **Paragraph mode on a file of only blank lines**: returns [`undef`](undef)
  immediately — there is no non-empty paragraph to yield.
- **Slurp mode, empty file**: first call returns `''` (defined,
  zero-length); the second returns [`undef`](undef). Do not branch on
  truthiness of the first read.
- **Fixed-record mode with a short read at EOF**: returns the
  remaining bytes (possibly fewer than `N`), then [`undef`](undef) on the
  next call. Check [`length`](length) if you need exactly `N`.
- **The `ARGV` magic handle**: when reading from `*ARGV`, `eof()`
  with no argument returns true only at the very end of **all**
  `@ARGV` files, while `eof(ARGV)` is true at the end of **each**
  file. You cannot use the `defined(readline) or die "...: $!"`
  idiom against `*ARGV` to distinguish EOF from error — open each
  filename yourself if you need that.
- **Already-closed handle**: `readline` returns [`undef`](undef) and sets
  [`$!`](../perlvar) to `"Bad file descriptor"`. Under `use warnings` a
  `readline() on closed filehandle` warning is emitted.
- **Encoding layers**: `readline` returns whatever the handle's
  PerlIO stack produces. A `:utf8` or `:encoding(...)` layer decodes
  bytes into characters; a `:raw` handle returns bytes. Mixing a
  multi-byte [`$/`](../perlvar) with a byte handle can split characters.
- **Mid-record [`$/`](../perlvar) change**: only the next `readline` call observes
  the new separator. Any already-buffered data is re-scanned against
  it.
- **`<FH>` vs. `<$fh>` vs. `<>`**: these are all `readline` under
  the hood. `<FH>` reads from the typeglob `FH`; `<$fh>` reads from
  the handle in `$fh`; `<>` (or `<<>>` for safer filename handling)
  reads from `*ARGV`. The `<pattern>` form with any other content
  is [`glob`](glob), not `readline` — a different function entirely.
- **Loop condition assignment**: `while (my $line = <$fh>) { ... }`
  tests [`defined`](defined), not truth, only because the parser rewrites it.
  `while (($line = <$fh>)) { ... }` with the extra parentheses does
  **not** get the rewrite, and will loop forever on input containing
  `"0\n"`.

## Differences from upstream

Fully compatible with upstream Perl 5.42.

## See also

- [`open`](open) — obtain the filehandle that `readline` consumes
- [`read`](read) — fixed-length byte read that ignores [`$/`](../perlvar); use
  when you want a byte count, not a record
- [`getc`](getc) — single-character read, likewise ignoring [`$/`](../perlvar)
- [`eof`](eof) — test whether the next `readline` would return
  [`undef`](undef); behaves specially for `*ARGV`
- [`$/`](../perlvar) — input record separator; controls line,
  paragraph, slurp, and fixed-record modes
- [`$.`](../perlvar) — current input line number, incremented by
  every successful `readline`