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

Syntax

  • read [-Aer] [-d delimiter] [-P|-p prompt] 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.

By default, the input line is read up to a newline character. If the -d (--delimiter) option is specified, the input line is read up to the specified delimiter character instead. The delimiter character must be a single character.

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.

-d delimiter
--delimiter=delimiter

Read up to the specified delimiter character instead of a newline.

-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.

  • The delimiter is a newline.

-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 is 0 if the read built-in successfully reads a line. If the end of the input is reached, the exit status is 1. The variables are assigned the words read so far. If a variable is read-only, the exit status is 2. If the standard input is unreadable, the exit status is 3. In case of a syntax error in the command line arguments, the exit status is 4.

Notes

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

The POSIX standard defines the -d and -r options only. Other options cannot be used in the POSIXly-correct mode. Only the exit status 0 and 1 are portable; for other error conditions, the exit status may be different in other shells.

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