1READ(1P) POSIX Programmer's Manual READ(1P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 read — read from standard input into shell variables
13
15 read [-r] var...
16
18 The read utility shall read a single logical line from standard input
19 into one or more shell variables.
20 By default, unless the -r option is specified, <backslash> shall act as
22 an escape character. An unescaped <backslash> shall preserve the lit‐
23 eral value of the following character, with the exception of a <new‐
24 line>. If a <newline> follows the <backslash>, the read utility shall
25 interpret this as line continuation. The <backslash> and <newline>
26 shall be removed before splitting the input into fields. All other
27 unescaped <backslash> characters shall be removed after splitting the
28 input into fields.
29 If standard input is a terminal device and the invoking shell is inter‐
31 active, read shall prompt for a continuation line when it reads an
32 input line ending with a <backslash> <newline>, unless the -r option is
33 specified.
34 The terminating <newline> (if any) shall be removed from the input and
36 the results shall be split into fields as in the shell for the results
37 of parameter expansion (see Section 2.6.5, Field Splitting); the first
38 field shall be assigned to the first variable var, the second field to
39 the second variable var, and so on. If there are fewer fields than
40 there are var operands, the remaining vars shall be set to empty
41 strings. If there are fewer vars than fields, the last var shall be set
42 to a value comprising the following elements:
43 * The field that corresponds to the last var in the normal assignment
45 sequence described above
46 * The delimiter(s) that follow the field corresponding to the last
48 var
49 * The remaining fields and their delimiters, with trailing IFS white
51 space ignored
52 The setting of variables specified by the var operands shall affect the
54 current shell execution environment; see Section 2.12, Shell Execution
55 Environment. If it is called in a subshell or separate utility execu‐
56 tion environment, such as one of the following:
57 (read foo)
60 nohup read ...
61 find . -exec read ... \;
62 it shall not affect the shell variables in the caller's environment.
64
66 The read utility shall conform to the Base Definitions volume of
67 POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
68 The following option is supported:
70 -r Do not treat a <backslash> character in any special way. Con‐
72 sider each <backslash> to be part of the input line.
73
75 The following operand shall be supported:
76 var The name of an existing or nonexisting shell variable.
78
80 The standard input shall be a text file.
81
83 None.
84
86 The following environment variables shall affect the execution of read:
87 IFS Determine the internal field separators used to delimit
89 fields; see Section 2.5.3, Shell Variables.
90 LANG Provide a default value for the internationalization vari‐
92 ables that are unset or null. (See the Base Definitions vol‐
93 ume of POSIX.1‐2017, Section 8.2, Internationalization Vari‐
94 ables for the precedence of internationalization variables
95 used to determine the values of locale categories.)
96 LC_ALL If set to a non-empty string value, override the values of
98 all the other internationalization variables.
99 LC_CTYPE Determine the locale for the interpretation of sequences of
101 bytes of text data as characters (for example, single-byte as
102 opposed to multi-byte characters in arguments).
103 LC_MESSAGES
105 Determine the locale that should be used to affect the format
106 and contents of diagnostic messages written to standard
107 error.
108 NLSPATH Determine the location of message catalogs for the processing
110 of LC_MESSAGES.
111 PS2 Provide the prompt string that an interactive shell shall
113 write to standard error when a line ending with a <backslash>
114 <newline> is read and the -r option was not specified.
115
117 Default.
118
120 Not used.
121
123 The standard error shall be used for diagnostic messages and prompts
124 for continued input.
125
127 None.
128
130 None.
131
133 The following exit values shall be returned:
134 0 Successful completion.
136 >0 End-of-file was detected or an error occurred.
138
140 Default.
141 The following sections are informative.
143
145 The -r option is included to enable read to subsume the purpose of the
146 line utility, which is not included in POSIX.1‐2008.
147
149 The following command:
150 while read -r xx yy
153 do
154 printf "%s %s\n$yy$xx"
155 done < input_file
156 prints a file with the first field of each line moved to the end of the
158 line.
159
161 The read utility historically has been a shell built-in. It was sepa‐
162 rated off into its own utility to take advantage of the richer descrip‐
163 tion of functionality introduced by this volume of POSIX.1‐2017.
164 Since read affects the current shell execution environment, it is gen‐
166 erally provided as a shell regular built-in. If it is called in a sub‐
167 shell or separate utility execution environment, such as one of the
168 following:
169 (read foo)
172 nohup read ...
173 find . -exec read ... \;
174 it does not affect the shell variables in the environment of the call‐
176 er.
177 Although the standard input is required to be a text file, and there‐
179 fore will always end with a <newline> (unless it is an empty file), the
180 processing of continuation lines when the -r option is not used can
181 result in the input not ending with a <newline>. This occurs if the
182 last line of the input file ends with a <backslash> <newline>. It is
183 for this reason that ``if any'' is used in ``The terminating <newline>
184 (if any) shall be removed from the input'' in the description. It is
185 not a relaxation of the requirement for standard input to be a text
186 file.
187
189 None.
190
192 Chapter 2, Shell Command Language
193 The Base Definitions volume of POSIX.1‐2017, Chapter 8, Environment
195 Variables, Section 12.2, Utility Syntax Guidelines
196
198 Portions of this text are reprinted and reproduced in electronic form
199 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
200 table Operating System Interface (POSIX), The Open Group Base Specifi‐
201 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
202 Electrical and Electronics Engineers, Inc and The Open Group. In the
203 event of any discrepancy between this version and the original IEEE and
204 The Open Group Standard, the original IEEE and The Open Group Standard
205 is the referee document. The original Standard can be obtained online
206 at http://www.opengroup.org/unix/online.html .
207 Any typographical or formatting errors that appear in this page are
209 most likely to have been introduced during the conversion of the source
210 files to man page format. To report such errors, see https://www.ker‐
211 nel.org/doc/man-pages/reporting_bugs.html .
212IEEE/The Open Group 2017 READ(1P)