1READ(P) POSIX Programmer's Manual READ(P)
2
6 read - read a line from standard input
7
9 read [-r] var...
10
12 The read utility shall read a single line from standard input.
13 By default, unless the -r option is specified, backslash ( '\' ) shall
15 act as an escape character, as described in Escape Character (Back‐
16 slash) . If standard input is a terminal device and the invoking shell
17 is interactive, read shall prompt for a continuation line when:
18 * The shell reads an input line ending with a backslash, unless the -r
20 option is specified.
21 * A here-document is not terminated after a <newline> is entered.
23 The line shall be split into fields as in the shell (see Field Split‐
25 ting ); the first field shall be assigned to the first variable var,
26 the second field to the second variable var, and so on. If there are
27 fewer var operands specified than there are fields, the leftover fields
28 and their intervening separators shall be assigned to the last var. If
29 there are fewer fields than vars, the remaining vars shall be set to
30 empty strings.
31 The setting of variables specified by the var operands shall affect the
33 current shell execution environment; see Shell Execution Environment .
34 If it is called in a subshell or separate utility execution environ‐
35 ment, such as one of the following:
36 (read foo)
39 nohup read ...
40 find . -exec read ... \;
41 it shall not affect the shell variables in the caller's environment.
43
45 The read utility shall conform to the Base Definitions volume of
46 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
47 The following option is supported:
49 -r Do not treat a backslash character in any special way. Consider
51 each backslash to be part of the input line.
52
55 The following operand shall be supported:
56 var The name of an existing or nonexisting shell variable.
58
61 The standard input shall be a text file.
62
64 None.
65
67 The following environment variables shall affect the execution of read:
68 IFS Determine the internal field separators used to delimit fields;
70 see Shell Variables .
71 LANG Provide a default value for the internationalization variables
73 that are unset or null. (See the Base Definitions volume of
74 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
75 ables for the precedence of internationalization variables used
76 to determine the values of locale categories.)
77 LC_ALL If set to a non-empty string value, override the values of all
79 the other internationalization variables.
80 LC_CTYPE
82 Determine the locale for the interpretation of sequences of
83 bytes of text data as characters (for example, single-byte as
84 opposed to multi-byte characters in arguments).
85 LC_MESSAGES
87 Determine the locale that should be used to affect the format
88 and contents of diagnostic messages written to standard error.
89 NLSPATH
91 Determine the location of message catalogs for the processing of
92 LC_MESSAGES .
93 PS2 Provide the prompt string that an interactive shell shall write
95 to standard error when a line ending with a backslash is read
96 and the -r option was not specified, or if a here-document is
97 not terminated after a <newline> is entered.
98
101 Default.
102
104 Not used.
105
107 The standard error shall be used for diagnostic messages and prompts
108 for continued input.
109
111 None.
112
114 None.
115
117 The following exit values shall be returned:
118 0 Successful completion.
120 >0 End-of-file was detected or an error occurred.
122
125 Default.
126 The following sections are informative.
128
130 The -r option is included to enable read to subsume the purpose of the
131 line utility, which is not included in IEEE Std 1003.1-2001.
132 The results are undefined if an end-of-file is detected following a
134 backslash at the end of a line when -r is not specified.
135
137 The following command:
138 while read -r xx yy
141 do
142 printf "%s %s\n" "$yy" "$xx"
143 done < input_file
144 prints a file with the first field of each line moved to the end of the
146 line.
147
149 The read utility historically has been a shell built-in. It was sepa‐
150 rated off into its own utility to take advantage of the richer descrip‐
151 tion of functionality introduced by this volume of
152 IEEE Std 1003.1-2001.
153 Since read affects the current shell execution environment, it is gen‐
155 erally provided as a shell regular built-in. If it is called in a sub‐
156 shell or separate utility execution environment, such as one of the
157 following:
158 (read foo)
161 nohup read ...
162 find . -exec read ... \;
163 it does not affect the shell variables in the environment of the call‐
165 er.
166
168 None.
169
171 Shell Command Language
172
174 Portions of this text are reprinted and reproduced in electronic form
175 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
176 -- Portable Operating System Interface (POSIX), The Open Group Base
177 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
178 Electrical and Electronics Engineers, Inc and The Open Group. In the
179 event of any discrepancy between this version and the original IEEE and
180 The Open Group Standard, the original IEEE and The Open Group Standard
181 is the referee document. The original Standard can be obtained online
182 at http://www.opengroup.org/unix/online.html .
183IEEE/The Open Group 2003 READ(P)