NAME

read — read from standard input into shell variables

SYNOPSIS

read [-r] [-d delim] var...

DESCRIPTION

The read utility shall read a single logical line from standard input into one or more shell variables.

If the -r option is not specified, <backslash> shall act as an escape character. An unescaped <backslash> shall preserve the literal value of a following <backslash> and shall prevent a following byte (if any) from being used to split fields, with the exception of either <newline> or the logical line delimiter specified with the -d delim option (if it is used and delim is not <newline>); it is unspecified which. If this excepted character follows the <backslash>, the read utility shall interpret this as line continuation. The <backslash> and the excepted character shall be removed before splitting the input into fields. All other unescaped <backslash> characters shall be removed after splitting the input into fields.

If standard input is a terminal device and the invoking shell is interactive, read shall prompt for a continuation line when it reads an input line ending with a <backslash> <newline>, unless the -r option is specified.

The terminating logical line delimiter (if any) shall be removed from the input. Then, if the shell variable IFS (see 2.5.3 Shell Variables) is set, and its value is an empty string, the resulting data shall be assigned to the variable named by the first var operand, and the variables named by other var operands (if any) shall be set to the empty string. No other processing shall be performed in this case.

If IFS is unset, or is set to any non-empty value, then a modified version of the field splitting algorithm specified in 2.6.5 Field Splitting shall be applied, with the modifications as follows:

1. The input to the algorithm shall be the logical line (minus terminating delimiter) that was read from standard input, and shall be considered as a single initial field, all of which resulted from expansions, with any escaped byte and the preceding <backslash> escape character treated as if they were the result of a quoted expansion, and all other bytes treated as if they were the results of unquoted expansions.

2. The loop over the contents of that initial field shall cease when either the input is empty or n output fields have been generated, where n is one less than the number of var operands passed to the read utility. Any remaining input in the original field being processed shall be returned to the read utility "unsplit"; that is, unmodified except that any leading or trailing IFS white space, as defined in 2.6.5 Field Splitting, shall be removed.

The specified var operands shall be processed in the order they appear on the command line, and the output fields generated by the field splitting algorithm shall be used in the order they were generated, by repeating the following checks until neither is true:

• If more than one var operand is yet to be processed and one or more output fields are yet to be used, the variable named by the first unprocessed var operand shall be assigned the value of the first unused output field.

• If exactly one var operand is yet to be processed and there was some remaining unsplit input returned from the modified field splitting algorithm, the variable named by the unprocessed var operand shall be assigned the unsplit input.

If there are still one or more unprocessed var operands, each of the variables names by those operands shall be assigned an empty string.

Note that in the case where just one var operand is given on the read command line, the modified field splitting algorithm ceases after producing zero output fields and simply returns the original input field, with any leading and trailing IFS white space removed, as unsplit input. This unsplit input is assigned to the variable named by the var operand.

The setting of variables specified by the var operands shall affect the current shell execution environment; see 2.13 Shell Execution Environment. An error in setting any variable (such as if a var has previously been marked readonly) shall be considered an error of read processing, and shall result in a return value greater than one. Variables named before the one generating the error shall be set as described above; it is unspecified whether variables named later shall be set as above, or read simply ceases processing when the error occurs, leaving later named variables unaltered. If read is called in a subshell or separate utility execution environment, such as one of the following:

(read foo)
nohup read ...
find . -exec read ... \;

it shall not affect the shell variables in the caller's environment.

If end-of-file is detected before a terminating logical line delimiter is encountered, the variables specified by the var operands shall be set as described above and the exit status shall be 1.

OPTIONS

The read utility shall conform to XBD 12.2 Utility Syntax Guidelines.

The following options shall be supported:

-d delim

If delim consists of one single-byte character, that byte shall be used as the logical line delimiter. If delim is the null string, the logical line delimiter shall be the null byte. Otherwise, the behavior is unspecified.

-r

Do not treat a <backslash> character in any special way. Consider each <backslash> to be part of the input line.

OPERANDS

The following operand shall be supported:

var

The name of an existing or nonexisting shell variable. If a var operand names the variable IFS , the behavior is unspecified.

If a var operand names one of the variables LANG , LC_CTYPE , or LC_ALL and the new value assigned to the variable would change how the bytes in IFS form characters, or which characters in IFS are considered to be IFS white space (see 2.6.5 Field Splitting), it is unspecified what effects, if any, the change has on how read performs field splitting.

STDIN

If the -d delim option is not specified, or if it is specified and delim is not the null string, the standard input shall contain zero or more bytes (which need not form valid characters) and shall not contain any null bytes.

If the -d delim option is specified and delim is the null string, the standard input shall contain zero or more bytes (which need not form valid characters).

INPUT FILES

None.

ENVIRONMENT VARIABLES

The following environment variables shall affect the execution of read:

IFS

Determine the internal field separators used to delimit fields; see 2.5.3 Shell Variables.

LANG

Provide a default value for the internationalization variables that are unset or null. (See XBD 8.2 Internationalization Variables for the precedence of internationalization variables used to determine the values of locale categories.)

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-byte as opposed to multi-byte characters in arguments).

LC_MESSAGES

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

NLSPATH

^[XSI] Determine the location of messages objects and message catalogs.

PS2

Provide the prompt string that an interactive shell shall write to standard error when a line ending with a <backslash> <newline> is read and the -r option was not specified.

ASYNCHRONOUS EVENTS

Default.

STDOUT

Not used.

STDERR

The standard error shall be used for diagnostic messages and prompts for continued input.

OUTPUT FILES

None.

EXTENDED DESCRIPTION

None.

EXIT STATUS

The following exit values shall be returned:

 0

Successful completion.

 1

End-of-file was detected.

>1

An error occurred.

CONSEQUENCES OF ERRORS

Default.

APPLICATION USAGE

This utility is required to be intrinsic. See 1.7 Intrinsic Utilities for details.

The -r option is included to enable read to subsume the purpose of the line utility, which is not included in POSIX.1-2024.

The -d delim option enables reading up to an arbitrary single-byte delimiter. When delim is the null string, the delimiter is the null byte and this allows read to be used to process null-terminated lists of pathnames (as produced by the find -print0 primary), with correct handling of pathnames that contain <newline> characters. Note that in order to specify the null string as the delimiter, -d and delim need to be specified as two separate arguments. Implementations differ in their handling of <backslash> for line continuation when -d delim is specified (and delim is not <newline>); some treat <backslash>delim (or <backslash><NUL> if delim is the null string) as a line continuation, whereas others still treat <backslash><newline> as a line continuation. Consequently, portable applications need to specify -r whenever they specify -d delim (and delim is not <newline>).

When reading a pathname it is inadvisable to use the contents of the first var operand, if non-empty, when the exit status of read is 1, as it is likely the result of the command used to generate the list of pathnames (for example find with -print or -print0) being terminated after it has written a partial pathname, and consequently using it could result in the wrong pathname being processed.

Since the var operands are processed in the order specified on the command line, if any variable name is specified more than once as a var operand, the last assignment made is the one that is in effect when read returns, including when an empty string is assigned because no field data was available.

EXAMPLES

The following command:

while read -r xx yy
do
    printf "%s %s\n" "$yy" "$xx"
done < input_file

prints a file with the first field of each line moved to the end of the line.

RATIONALE

The read utility historically has been a shell built-in. It was separated off into its own utility to take advantage of the richer description of functionality introduced by this volume of POSIX.1-2024.

Since read affects the current shell execution environment, it is required to be intrinsic. If it is called in a subshell or separate utility execution environment, such as one of the following:

(read foo)
nohup read ...
find . -exec read ... \;

it does not affect the shell variables in the environment of the caller.

Earlier versions of this standard required the standard input to be a text file, and therefore the results were undefined if the input was not empty and end-of-file was detected before a <newline> character was encountered. However, all of the most popular shell implementations have been found to have consistent behavior in this case, and so the behavior is now specified and the requirement for standard input to be a text file has been relaxed to allow non-empty input that does not end with a <newline>.

FUTURE DIRECTIONS

None.

SEE ALSO

2. Shell Command Language

XBD 8. Environment Variables, 12.2 Utility Syntax Guidelines

CHANGE HISTORY

First released in Issue 2.

Issue 7

Austin Group Interpretation 1003.1-2001 #194 is applied, clarifying the handling of the <backslash> escape character.

SD5-XCU-ERN-126 is applied, clarifying that input lines end with a <newline>.

The description of here-documents is removed from the read reference page.

POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0162 [958] is applied.

Issue 8

Austin Group Defect 243 is applied, adding the -d option and relaxing the requirement for standard input to be a text file.

Austin Group Defect 367 is applied, requiring that read distinguishes between detecting end-of-file and an error occurring, setting its exit status to one and greater than one, respectively.

Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be intrinsic.

Austin Group Defect 1122 is applied, changing the description of NLSPATH .

Austin Group Defect 1778 is applied, clarifying how field splitting is performed.

Austin Group Defect 1779 is applied, clarifying how an error in setting any variable affects the processing of variables named before or after the one generating the error.