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
11

NAME

13       read — read a line from standard input
14

SYNOPSIS

16       read [−r] var...
17

DESCRIPTION

19       The read utility shall read a single line from standard input.
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           (read foo)
59           nohup read ...
60           find . −exec read ... \;
61
62       it shall not affect the shell variables in the caller's environment.
63

OPTIONS

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

OPERANDS

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

STDIN

79       The standard input shall be a text file.
80

INPUT FILES

82       None.
83

ENVIRONMENT VARIABLES

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

ASYNCHRONOUS EVENTS

116       Default.
117

STDOUT

119       Not used.
120

STDERR

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

OUTPUT FILES

126       None.
127

EXTENDED DESCRIPTION

129       None.
130

EXIT STATUS

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

CONSEQUENCES OF ERRORS

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

APPLICATION USAGE

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

EXAMPLES

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

RATIONALE

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

FUTURE DIRECTIONS

186       None.
187

SEE ALSO

189       Chapter 2, Shell Command Language
190
191       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
206       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 .
210
211
212
213IEEE/The Open Group                  2013                             READ(1P)
Impressum