1READ(1P)                   POSIX Programmer's Manual                  READ(1P)
2
3
4

PROLOG

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

NAME

12       read — read from standard input into shell variables
13

SYNOPSIS

15       read [-r] var...
16

DESCRIPTION

18       The read utility shall read a single logical line from  standard  input
19       into one or more shell variables.
20
21       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
30       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
35       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
44        *  The field that corresponds to the last var in the normal assignment
45           sequence described above
46
47        *  The  delimiter(s)  that  follow the field corresponding to the last
48           var
49
50        *  The remaining fields and their delimiters, with trailing IFS  white
51           space ignored
52
53       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
58
59           (read foo)
60           nohup read ...
61           find . -exec read ... \;
62
63       it shall not affect the shell variables in the caller's environment.
64

OPTIONS

66       The read utility shall  conform  to  the  Base  Definitions  volume  of
67       POSIX.1‐2017, Section 12.2, Utility Syntax Guidelines.
68
69       The following option is supported:
70
71       -r        Do not treat a <backslash> character in any special way. Con‐
72                 sider each <backslash> to be part of the input line.
73

OPERANDS

75       The following operand shall be supported:
76
77       var       The name of an existing or nonexisting shell variable.
78

STDIN

80       The standard input shall be a text file.
81

INPUT FILES

83       None.
84

ENVIRONMENT VARIABLES

86       The following environment variables shall affect the execution of read:
87
88       IFS       Determine the  internal  field  separators  used  to  delimit
89                 fields; see Section 2.5.3, Shell Variables.
90
91       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
97       LC_ALL    If  set  to  a non-empty string value, override the values of
98                 all the other internationalization variables.
99
100       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
104       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
109       NLSPATH   Determine the location of message catalogs for the processing
110                 of LC_MESSAGES.
111
112       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

ASYNCHRONOUS EVENTS

117       Default.
118

STDOUT

120       Not used.
121

STDERR

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

OUTPUT FILES

127       None.
128

EXTENDED DESCRIPTION

130       None.
131

EXIT STATUS

133       The following exit values shall be returned:
134
135        0    Successful completion.
136
137       >0    End-of-file was detected or an error occurred.
138

CONSEQUENCES OF ERRORS

140       Default.
141
142       The following sections are informative.
143

APPLICATION USAGE

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

EXAMPLES

149       The following command:
150
151
152           while read -r xx yy
153           do
154               printf "%s %s\n$yy$xx"
155           done < input_file
156
157       prints a file with the first field of each line moved to the end of the
158       line.
159

RATIONALE

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
165       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
170
171           (read foo)
172           nohup read ...
173           find . -exec read ... \;
174
175       it  does not affect the shell variables in the environment of the call‐
176       er.
177
178       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

FUTURE DIRECTIONS

189       None.
190

SEE ALSO

192       Chapter 2, Shell Command Language
193
194       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
208       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 .
212
213
214
215IEEE/The Open Group                  2017                             READ(1P)
Impressum