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
13 read — read a line from standard input
14
16 read [−r] var...
17
19 The read utility shall read a single line from standard input.
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)
59 nohup read ...
60 find . −exec read ... \;
61 it shall not affect the shell variables in the caller's environment.
63
65 The read utility shall conform to the Base Definitions volume of
66 POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
67 The following option is supported:
69 −r Do not treat a <backslash> character in any special way. Con‐
71 sider each <backslash> to be part of the input line.
72
74 The following operand shall be supported:
75 var The name of an existing or nonexisting shell variable.
77
79 The standard input shall be a text file.
80
82 None.
83
85 The following environment variables shall affect the execution of read:
86 IFS Determine the internal field separators used to delimit
88 fields; see Section 2.5.3, Shell Variables.
89 LANG Provide a default value for the internationalization vari‐
91 ables that are unset or null. (See the Base Definitions vol‐
92 ume of POSIX.1‐2008, Section 8.2, Internationalization Vari‐
93 ables for the precedence of internationalization variables
94 used to determine the values of locale categories.)
95 LC_ALL If set to a non-empty string value, override the values of
97 all the other internationalization variables.
98 LC_CTYPE Determine the locale for the interpretation of sequences of
100 bytes of text data as characters (for example, single-byte as
101 opposed to multi-byte characters in arguments).
102 LC_MESSAGES
104 Determine the locale that should be used to affect the format
105 and contents of diagnostic messages written to standard
106 error.
107 NLSPATH Determine the location of message catalogs for the processing
109 of LC_MESSAGES.
110 PS2 Provide the prompt string that an interactive shell shall
112 write to standard error when a line ending with a <backslash>
113 <newline> is read and the −r option was not specified.
114
116 Default.
117
119 Not used.
120
122 The standard error shall be used for diagnostic messages and prompts
123 for continued input.
124
126 None.
127
129 None.
130
132 The following exit values shall be returned:
133 0 Successful completion.
135 >0 End-of-file was detected or an error occurred.
137
139 Default.
140 The following sections are informative.
142
144 The −r option is included to enable read to subsume the purpose of the
145 line utility, which is not included in POSIX.1‐2008.
146
148 The following command:
149 while read −r xx yy
151 do
152 printf "%s %s\n$yy$xx"
153 done < input_file
154 prints a file with the first field of each line moved to the end of the
156 line.
157
159 The read utility historically has been a shell built-in. It was sepa‐
160 rated off into its own utility to take advantage of the richer descrip‐
161 tion of functionality introduced by this volume of POSIX.1‐2008.
162 Since read affects the current shell execution environment, it is gen‐
164 erally provided as a shell regular built-in. If it is called in a sub‐
165 shell or separate utility execution environment, such as one of the
166 following:
167 (read foo)
169 nohup read ...
170 find . −exec read ... \;
171 it does not affect the shell variables in the environment of the call‐
173 er.
174 Although the standard input is required to be a text file, and there‐
176 fore will always end with a <newline> (unless it is an empty file), the
177 processing of continuation lines when the −r option is not used can
178 result in the input not ending with a <newline>. This occurs if the
179 last line of the input file ends with a <backslash> <newline>. It is
180 for this reason that ``if any'' is used in ``The terminating <newline>
181 (if any) shall be removed from the input'' in the description. It is
182 not a relaxation of the requirement for standard input to be a text
183 file.
184
186 None.
187
189 Chapter 2, Shell Command Language
190 The Base Definitions volume of POSIX.1‐2008, Chapter 8, Environment
192 Variables, Section 12.2, Utility Syntax Guidelines
193
195 Portions of this text are reprinted and reproduced in electronic form
196 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
197 -- Portable Operating System Interface (POSIX), The Open Group Base
198 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
199 cal and Electronics Engineers, Inc and The Open Group. (This is
200 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
201 event of any discrepancy between this version and the original IEEE and
202 The Open Group Standard, the original IEEE and The Open Group Standard
203 is the referee document. The original Standard can be obtained online
204 at http://www.unix.org/online.html .
205 Any typographical or formatting errors that appear in this page are
207 most likely to have been introduced during the conversion of the source
208 files to man page format. To report such errors, see https://www.ker‐
209 nel.org/doc/man-pages/reporting_bugs.html .
210IEEE/The Open Group 2013 READ(1P)