The read built-in reads a line from the standard input.

Syntax

  • read [-Aer] [-P|-p] variable…

Description

The read built-in reads a line of string from the standard input and assigns it to the specified variables.

If the -r (--raw-mode) option is specified, all characters in the line are treated literally.

If the -r (--raw-mode) option is not specified, backslashes in the line are treated as quotations. If a backslash is at the end of the line, it is treated as a line continuation. When the built-in reads the next line, the PS2 variable is used as a prompt if the shell is interactive and the standard input is a terminal.

The input line is subject to field splitting. The resulting words are assigned to variables in order. If there are more words than variables, the last variable is assigned all the remaining words (as if the words were not split). If the words are fewer than variables, the remaining variables are assigned empty strings.

Options

-A
--array

Make the last variable an array. Instead of assigning a concatenation of the remaining words to a normal variable, the words are assigned to an array.

-e
--line-editing

Use line-editing to read the line.

To use line-editing, all of the following conditions must also be met:

  • The shell is interactive.

  • The vi or emacs option is enabled.

  • The standard input and standard error are connected to a terminal.

-P
--ps1

Print the PS1 variable as a prompt before reading the (first) line if the shell is interactive and the standard input is a terminal.

-p prompt
--prompt=prompt

Print the specified prompt before reading the (first) line if the shell is interactive and the standard input is a terminal.

-r
--raw-mode

Don’t treat backslashes as quotations.

Operands

variables

Names of variables to which input words are assigned.

Exit status

The exit status of the read built-in is zero unless there is any error.

Note that the exit status is non-zero if an end of input is encountered before reading the entire line.

Notes

The read built-in is a mandatory built-in.

The POSIX standard defines the -r option only: other options cannot be used in the POSIXly-correct mode.

The PS1R and PS1S variables affect the behavior of line-editing if the PS1 prompt is used. The same for PS2.