read - read a line from standard input

read is a POSIX shell built-in command that reads a line from standard input and sequentially assigns the individual input line arguments as values to the shell variables specified in the call.

The only argument separators that read recognizes are the characters assigned to the IFS shell variable, the defaults being blanks, tabs and newline characters.

If read appears in a shell script and standard input has not been redirected, the script halts execution in order to read your next input from standard input. The script resumes execution as soon as you enter a newline character (see also Examples on "read read a line from standard input").

Syntax

read  [-option][ name?prompt][ name]...

option

-p

The command does not read from the standard input but from the pipeline for the process created using |&. When the end-of-file is reached in the pipeline, the input is cleared to permit |& to generate a new process.

-r

In raw mode the backslash \ at line end has no special function, i.e. the line is not continued.

-s

The input is written as a command to the history file.

-ufile_descriptor

The command reads from the single-figure file_descriptor instead of from the standard input. The file descriptor can be opened using the exec command. The default value of file descriptor is 0.

name

Name of the shell variable to which the corresponding input line argument is assigned. The first argument is assigned to the first name, the second argument goes to the second, and so on, with the last name assigned whatever remains on the input line.

The names of shell variables must start with a letter or an underscore (_) and must consist of letters, underscores and digits only.

Any leftover arguments in the input line are assigned to the last variable specified in the read command line.

Any leftover variables of the read command are assigned the null string.

If the first argument contains a ?, the rest of the word is written to standard error as a prompt.

name not specified:
REPLY is used for name.

Exit status

0	when read executes successfully
>0	when no input is received, i.e. EOF is encountered.

Error

sh: text: not an identifier

This error message may have the following causes:

• either you did not specify a variable name on the command line, or

• the name you specified contains illegal characters.

read: missing arguments

You called read without arguments.

Variable

IFS

Input field separator (argument delimiter). The default values are blank, tab and newline.

PS2

Provide the prompt string that an interactive shell will write to standard error when a line ending with a backslash is read and the -r option was not specified, or if a here-document is not terminated after a newline character is entered.

Locale

The following environment variables affect the execution of read:

LANG

Provide a default value for the internationalization variables that are unset or null. If LANG is unset of null, the corresponding value from the implementation-specific default locale will be used. If any of the internationalization variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalization variables.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files), the classification of characters as upper- to lower-case, and the mapping of characters from one case to the other.

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

NLSPATH

Determine the location of message catalogs for the processing of LC_MESSAGES.

Example 1

The read command is invoked in a script named readtest, which contains the following:

: Invoked with sh readtest, halts for input
echo Please enter a customer name:
read customer1 customer2 customer3
if [ -z "$customer1" ]
then exit 5
else echo Customer1: $customer1
     echo Customer2: $customer2
     echo Customer3: $customer3
fi

Invocation of the readtest script file:

$ sh readtest
Please enter a customer name:
Shaw Bowden Pitman Potter
Customer1: Shaw
Customer2: Bowden
Customer3: Pitman Potter

After invocation, the shell script issues the message specified in the echo command and invokes read. The script halts, and the entered customer names are then read in.
The newline character terminates the input line for read. The third variable customer3 is assigned two names, since four arguments were specified in the input line.

Example 2

Use of the read command to read in the first line from a file:

$ read line < /etc/group
$ echo $line
root::0:root

In this case, the first line of the file /etc/group will always be read, even if read is invoked repeatedly.

Example 3

The following shell script makes use of the read command in order to read in lines from a file successively:

: Invoked with sh readinall
exec < /etc/group
for i in 1 2 3 4 5 6 7
do
  read record$i
  eval echo record$i: \$record$i
done

In the shell script readinall, the shell built-in exec redirects the standard input to the file /etc/group for the following read command.
Owing to the for loop, read is invoked seven times in the script. Each invocation positions the read pointer on the next line, thus causing echo to output the first seven lines of the /etc/group file in succession:

$ sh readinall
record1: root::0:root
record2: daemon::1:daemon
record3: sys::2:sys:
record4: bin::3:bin,admin
record5: uucp::4:
record6: ces::5:
record7: other::10:gast,mgast,tele

To evaluate the argument \$record$i correctly, the shell has to interpret the echo command line twice; hence the inclusion of eval.

At the first attempt the shell only interprets $i, as the first dollar sign is escaped by the backslash.

At the second attempt the shell interprets $record[1-7].

See also

exec