Un outil pour savoir si une commande est posix - retour accueil
git clone git://bebou.netlib.re/isposix
Log | Files | Refs | README |
read.html (19953B)
1 <!-- Copyright 2001-2024 IEEE and The Open Group, All Rights Reserved -->
2 <!DOCTYPE HTML>
3 <html lang="en">
4 <head>
5 <meta name="generator" content="HTML Tidy for HTML5 for Linux version 5.8.0">
6 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
7 <link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group rhtm tool v1.2.4 -->
8 <!-- Copyright (c) 2001-2024 The Open Group, All Rights Reserved -->
9 <title>read</title>
10 </head>
11 <body bgcolor="white">
12 <div class="NAVHEADER">
13 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
14 <tr class="nav">
15 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/pwd.html" accesskey="P"><<<
16 Previous</a></td>
17 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
18 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/readlink.html" accesskey="N">Next
19 >>></a></td>
20 </tr>
21 </table>
22 <hr align="left" width="100%"></div>
23 <script language="JavaScript" src="../jscript/codes.js"></script><basefont size="3">
24 <center><font size="2">The Open Group Base Specifications Issue 8<br>
25 IEEE Std 1003.1-2024<br>
26 Copyright © 2001-2024 The IEEE and The Open Group</font></center>
27 <hr size="2" noshade>
28 <a name="top" id="top"></a> <a name="read" id="read"></a> <a name="tag_20_100" id="tag_20_100"></a><!-- read -->
29 <h4 class="mansect"><a name="tag_20_100_01" id="tag_20_100_01"></a>NAME</h4>
30 <blockquote>read — read from standard input into shell variables</blockquote>
31 <h4 class="mansect"><a name="tag_20_100_02" id="tag_20_100_02"></a>SYNOPSIS</h4>
32 <blockquote class="synopsis">
33 <p><code><tt>read</tt> <b>[</b><tt>-r</tt><b>] [</b><tt>-d</tt> <i>delim</i><b>]</b> <i>var</i><tt>...</tt></code></p>
34 </blockquote>
35 <h4 class="mansect"><a name="tag_20_100_03" id="tag_20_100_03"></a>DESCRIPTION</h4>
36 <blockquote>
37 <p>The <i>read</i> utility shall read a single logical line from standard input into one or more shell variables.</p>
38 <p>If the <b>-r</b> option is not specified, <backslash> shall act as an escape character. An unescaped <backslash>
39 shall preserve the literal value of a following <backslash> and shall prevent a following byte (if any) from being used to
40 split fields, with the exception of either <newline> or the logical line delimiter specified with the <b>-d</b> <i>delim</i>
41 option (if it is used and <i>delim</i> is not <newline>); it is unspecified which. If this excepted character follows the
42 <backslash>, the <i>read</i> utility shall interpret this as line continuation. The <backslash> and the excepted
43 character shall be removed before splitting the input into fields. All other unescaped <backslash> characters shall be
44 removed after splitting the input into fields.</p>
45 <p>If standard input is a terminal device and the invoking shell is interactive, <i>read</i> shall prompt for a continuation line
46 when it reads an input line ending with a <backslash> <newline>, unless the <b>-r</b> option is specified.</p>
47 <p>The terminating logical line delimiter (if any) shall be removed from the input. Then, if the shell variable <i>IFS</i> (see
48 <a href="../utilities/V3_chap02.html#tag_19_05_03"><i>2.5.3 Shell Variables</i></a> ) is set, and its value is an empty string, the
49 resulting data shall be assigned to the variable named by the first <i>var</i> operand, and the variables named by other <i>var</i>
50 operands (if any) shall be set to the empty string. No other processing shall be performed in this case.</p>
51 <p>If <i>IFS</i> is unset, or is set to any non-empty value, then a modified version of the field splitting algorithm specified in
52 <a href="../utilities/V3_chap02.html#tag_19_06_05"><i>2.6.5 Field Splitting</i></a> shall be applied, with the modifications as
53 follows:</p>
54 <ol>
55 <li>
56 <p>The input to the algorithm shall be the logical line (minus terminating delimiter) that was read from standard input, and shall
57 be considered as a single initial field, all of which resulted from expansions, with any escaped byte and the preceding
58 <backslash> escape character treated as if they were the result of a quoted expansion, and all other bytes treated as if they
59 were the results of unquoted expansions.</p>
60 </li>
61 <li>
62 <p>The loop over the contents of that initial field shall cease when either the input is empty or <i>n</i> output fields have been
63 generated, where <i>n</i> is one less than the number of <i>var</i> operands passed to the <i>read</i> utility. Any remaining input
64 in the original field being processed shall be returned to the <i>read</i> utility "unsplit"; that is, unmodified except that any
65 leading or trailing <i>IFS</i> white space, as defined in <a href="../utilities/V3_chap02.html#tag_19_06_05"><i>2.6.5 Field
66 Splitting</i></a> , shall be removed.</p>
67 </li>
68 </ol>
69 <p>The specified <i>var</i> operands shall be processed in the order they appear on the command line, and the output fields
70 generated by the field splitting algorithm shall be used in the order they were generated, by repeating the following checks until
71 neither is true:</p>
72 <ul>
73 <li>
74 <p>If more than one <i>var</i> operand is yet to be processed and one or more output fields are yet to be used, the variable named
75 by the first unprocessed <i>var</i> operand shall be assigned the value of the first unused output field.</p>
76 </li>
77 <li>
78 <p>If exactly one <i>var</i> operand is yet to be processed and there was some remaining unsplit input returned from the modified
79 field splitting algorithm, the variable named by the unprocessed <i>var</i> operand shall be assigned the unsplit input.</p>
80 </li>
81 </ul>
82 <p>If there are still one or more unprocessed <i>var</i> operands, each of the variables names by those operands shall be assigned
83 an empty string.</p>
84 <p>Note that in the case where just one <i>var</i> operand is given on the <i>read</i> command line, the modified field splitting
85 algorithm ceases after producing zero output fields and simply returns the original input field, with any leading and trailing
86 <i>IFS</i> white space removed, as unsplit input. This unsplit input is assigned to the variable named by the <i>var</i>
87 operand.</p>
88 <p>The setting of variables specified by the <i>var</i> operands shall affect the current shell execution environment; see <a href=
89 "../utilities/V3_chap02.html#tag_19_13"><i>2.13 Shell Execution Environment</i></a> . An error in setting any variable (such as if
90 a <i>var</i> has previously been marked <i>readonly</i>) shall be considered an error of <i>read</i> processing, and shall result
91 in a return value greater than one. Variables named before the one generating the error shall be set as described above; it is
92 unspecified whether variables named later shall be set as above, or <i>read</i> simply ceases processing when the error occurs,
93 leaving later named variables unaltered. If <i>read</i> is called in a subshell or separate utility execution environment, such as
94 one of the following:</p>
95 <pre>
96 <tt>(read foo)
97 nohup read ...
98 find . -exec read ... \;
99 </tt></pre>
100 <p>it shall not affect the shell variables in the caller's environment.</p>
101 <p>If end-of-file is detected before a terminating logical line delimiter is encountered, the variables specified by the <i>var</i>
102 operands shall be set as described above and the exit status shall be 1.</p>
103 </blockquote>
104 <h4 class="mansect"><a name="tag_20_100_04" id="tag_20_100_04"></a>OPTIONS</h4>
105 <blockquote>
106 <p>The <i>read</i> utility shall conform to XBD <a href="../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax
107 Guidelines</i></a> .</p>
108 <p>The following options shall be supported:</p>
109 <dl compact>
110 <dd></dd>
111 <dt><b>-d</b> <i>delim</i></dt>
112 <dd>If <i>delim</i> consists of one single-byte character, that byte shall be used as the logical line delimiter. If <i>delim</i>
113 is the null string, the logical line delimiter shall be the null byte. Otherwise, the behavior is unspecified.</dd>
114 <dt><b>-r</b></dt>
115 <dd>Do not treat a <backslash> character in any special way. Consider each <backslash> to be part of the input
116 line.</dd>
117 </dl>
118 </blockquote>
119 <h4 class="mansect"><a name="tag_20_100_05" id="tag_20_100_05"></a>OPERANDS</h4>
120 <blockquote>
121 <p>The following operand shall be supported:</p>
122 <dl compact>
123 <dd></dd>
124 <dt><i>var</i></dt>
125 <dd>The name of an existing or nonexisting shell variable. If a <i>var</i> operand names the variable <i>IFS ,</i> the behavior is
126 unspecified.
127 <p>If a <i>var</i> operand names one of the variables <i>LANG ,</i> <i>LC_CTYPE ,</i> or <i>LC_ALL</i> and the new value assigned
128 to the variable would change how the bytes in <i>IFS</i> form characters, or which characters in <i>IFS</i> are considered to be
129 <i>IFS</i> white space (see <a href="../utilities/V3_chap02.html#tag_19_06_05"><i>2.6.5 Field Splitting</i></a> ), it is
130 unspecified what effects, if any, the change has on how <i>read</i> performs field splitting.</p>
131 </dd>
132 </dl>
133 </blockquote>
134 <h4 class="mansect"><a name="tag_20_100_06" id="tag_20_100_06"></a>STDIN</h4>
135 <blockquote>
136 <p>If the <b>-d</b> <i>delim</i> option is not specified, or if it is specified and <i>delim</i> is not the null string, the
137 standard input shall contain zero or more bytes (which need not form valid characters) and shall not contain any null bytes.</p>
138 <p>If the <b>-d</b> <i>delim</i> option is specified and <i>delim</i> is the null string, the standard input shall contain zero or
139 more bytes (which need not form valid characters).</p>
140 </blockquote>
141 <h4 class="mansect"><a name="tag_20_100_07" id="tag_20_100_07"></a>INPUT FILES</h4>
142 <blockquote>
143 <p>None.</p>
144 </blockquote>
145 <h4 class="mansect"><a name="tag_20_100_08" id="tag_20_100_08"></a>ENVIRONMENT VARIABLES</h4>
146 <blockquote>
147 <p>The following environment variables shall affect the execution of <i>read</i>:</p>
148 <dl compact>
149 <dd></dd>
150 <dt><i>IFS</i></dt>
151 <dd>Determine the internal field separators used to delimit fields; see <a href="../utilities/V3_chap02.html#tag_19_05_03"><i>2.5.3
152 Shell Variables</i></a> .</dd>
153 <dt><i>LANG</i></dt>
154 <dd>Provide a default value for the internationalization variables that are unset or null. (See XBD <a href=
155 "../basedefs/V1_chap08.html#tag_08_02"><i>8.2 Internationalization Variables</i></a> for the precedence of internationalization
156 variables used to determine the values of locale categories.)</dd>
157 <dt><i>LC_ALL</i></dt>
158 <dd>If set to a non-empty string value, override the values of all the other internationalization variables.</dd>
159 <dt><i>LC_CTYPE</i></dt>
160 <dd>Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as
161 opposed to multi-byte characters in arguments).</dd>
162 <dt><i>LC_MESSAGES</i></dt>
163 <dd><br>
164 Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.</dd>
165 <dt><i>NLSPATH</i></dt>
166 <dd><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
167 Determine the location of messages objects and message catalogs. <img src="../images/opt-end.gif" alt="[Option End]" border=
168 "0"></dd>
169 <dt><i>PS2</i></dt>
170 <dd>Provide the prompt string that an interactive shell shall write to standard error when a line ending with a <backslash>
171 <newline> is read and the <b>-r</b> option was not specified.</dd>
172 </dl>
173 </blockquote>
174 <h4 class="mansect"><a name="tag_20_100_09" id="tag_20_100_09"></a>ASYNCHRONOUS EVENTS</h4>
175 <blockquote>
176 <p>Default.</p>
177 </blockquote>
178 <h4 class="mansect"><a name="tag_20_100_10" id="tag_20_100_10"></a>STDOUT</h4>
179 <blockquote>
180 <p>Not used.</p>
181 </blockquote>
182 <h4 class="mansect"><a name="tag_20_100_11" id="tag_20_100_11"></a>STDERR</h4>
183 <blockquote>
184 <p>The standard error shall be used for diagnostic messages and prompts for continued input.</p>
185 </blockquote>
186 <h4 class="mansect"><a name="tag_20_100_12" id="tag_20_100_12"></a>OUTPUT FILES</h4>
187 <blockquote>
188 <p>None.</p>
189 </blockquote>
190 <h4 class="mansect"><a name="tag_20_100_13" id="tag_20_100_13"></a>EXTENDED DESCRIPTION</h4>
191 <blockquote>
192 <p>None.</p>
193 </blockquote>
194 <h4 class="mansect"><a name="tag_20_100_14" id="tag_20_100_14"></a>EXIT STATUS</h4>
195 <blockquote>
196 <p>The following exit values shall be returned:</p>
197 <dl compact>
198 <dd></dd>
199 <dt> 0</dt>
200 <dd>Successful completion.</dd>
201 <dt> 1</dt>
202 <dd>End-of-file was detected.</dd>
203 <dt>>1</dt>
204 <dd>An error occurred.</dd>
205 </dl>
206 </blockquote>
207 <h4 class="mansect"><a name="tag_20_100_15" id="tag_20_100_15"></a>CONSEQUENCES OF ERRORS</h4>
208 <blockquote>
209 <p>Default.</p>
210 </blockquote>
211 <hr>
212 <div class="box"><em>The following sections are informative.</em></div>
213 <h4 class="mansect"><a name="tag_20_100_16" id="tag_20_100_16"></a>APPLICATION USAGE</h4>
214 <blockquote>
215 <p>This utility is required to be intrinsic. See <a href="../utilities/V3_chap01.html#tag_18_07"><i>1.7 Intrinsic Utilities</i></a>
216 for details.</p>
217 <p>The <b>-r</b> option is included to enable <i>read</i> to subsume the purpose of the <i>line</i> utility, which is not included
218 in POSIX.1-2024.</p>
219 <p>The <b>-d</b> <i>delim</i> option enables reading up to an arbitrary single-byte delimiter. When <i>delim</i> is the null
220 string, the delimiter is the null byte and this allows <i>read</i> to be used to process null-terminated lists of pathnames (as
221 produced by the <a href="../utilities/find.html"><i>find</i></a> <b>-print0</b> primary), with correct handling of pathnames that
222 contain <newline> characters. Note that in order to specify the null string as the delimiter, <b>-d</b> and <i>delim</i> need
223 to be specified as two separate arguments. Implementations differ in their handling of <backslash> for line continuation when
224 <b>-d</b> <i>delim</i> is specified (and <i>delim</i> is not <newline>); some treat <backslash><i>delim</i> (or
225 <backslash><NUL> if <i>delim</i> is the null string) as a line continuation, whereas others still treat
226 <backslash><newline> as a line continuation. Consequently, portable applications need to specify <b>-r</b> whenever
227 they specify <b>-d</b> <i>delim</i> (and <i>delim</i> is not <newline>).</p>
228 <p>When reading a pathname it is inadvisable to use the contents of the first <i>var</i> operand, if non-empty, when the exit
229 status of <i>read</i> is 1, as it is likely the result of the command used to generate the list of pathnames (for example <a href=
230 "../utilities/find.html"><i>find</i></a> with <b>-print</b> or <b>-print0</b>) being terminated after it has written a partial
231 pathname, and consequently using it could result in the wrong pathname being processed.</p>
232 <p>Since the <i>var</i> operands are processed in the order specified on the command line, if any variable name is specified more
233 than once as a <i>var</i> operand, the last assignment made is the one that is in effect when <i>read</i> returns, including when
234 an empty string is assigned because no field data was available.</p>
235 </blockquote>
236 <h4 class="mansect"><a name="tag_20_100_17" id="tag_20_100_17"></a>EXAMPLES</h4>
237 <blockquote>
238 <p>The following command:</p>
239 <pre>
240 <tt>while read -r xx yy
241 do
242 printf "%s %s\n" "$yy" "$xx"
243 done < </tt><i>input_file</i><tt>
244 </tt></pre>
245 <p>prints a file with the first field of each line moved to the end of the line.</p>
246 </blockquote>
247 <h4 class="mansect"><a name="tag_20_100_18" id="tag_20_100_18"></a>RATIONALE</h4>
248 <blockquote>
249 <p>The <i>read</i> utility historically has been a shell built-in. It was separated off into its own utility to take advantage of
250 the richer description of functionality introduced by this volume of POSIX.1-2024.</p>
251 <p>Since <i>read</i> affects the current shell execution environment, it is required to be intrinsic. If it is called in a subshell
252 or separate utility execution environment, such as one of the following:</p>
253 <pre>
254 <tt>(read foo)
255 nohup read ...
256 find . -exec read ... \;
257 </tt></pre>
258 <p>it does not affect the shell variables in the environment of the caller.</p>
259 <p>Earlier versions of this standard required the standard input to be a text file, and therefore the results were undefined if the
260 input was not empty and end-of-file was detected before a <newline> character was encountered. However, all of the most
261 popular shell implementations have been found to have consistent behavior in this case, and so the behavior is now specified and
262 the requirement for standard input to be a text file has been relaxed to allow non-empty input that does not end with a
263 <newline>.</p>
264 </blockquote>
265 <h4 class="mansect"><a name="tag_20_100_19" id="tag_20_100_19"></a>FUTURE DIRECTIONS</h4>
266 <blockquote>
267 <p>None.</p>
268 </blockquote>
269 <h4 class="mansect"><a name="tag_20_100_20" id="tag_20_100_20"></a>SEE ALSO</h4>
270 <blockquote>
271 <p><a href="../utilities/V3_chap02.html#tag_19"><i>2. Shell Command Language</i></a></p>
272 <p>XBD <a href="../basedefs/V1_chap08.html#tag_08"><i>8. Environment Variables</i></a> , <a href=
273 "../basedefs/V1_chap12.html#tag_12_02"><i>12.2 Utility Syntax Guidelines</i></a></p>
274 </blockquote>
275 <h4 class="mansect"><a name="tag_20_100_21" id="tag_20_100_21"></a>CHANGE HISTORY</h4>
276 <blockquote>
277 <p>First released in Issue 2.</p>
278 </blockquote>
279 <h4 class="mansect"><a name="tag_20_100_22" id="tag_20_100_22"></a>Issue 7</h4>
280 <blockquote>
281 <p>Austin Group Interpretation 1003.1-2001 #194 is applied, clarifying the handling of the <backslash> escape character.</p>
282 <p>SD5-XCU-ERN-126 is applied, clarifying that input lines end with a <newline>.</p>
283 <p>The description of here-documents is removed from the <i>read</i> reference page.</p>
284 <p>POSIX.1-2008, Technical Corrigendum 2, XCU/TC2-2008/0162 [958] is applied.</p>
285 </blockquote>
286 <h4 class="mansect"><a name="tag_20_100_23" id="tag_20_100_23"></a>Issue 8</h4>
287 <blockquote>
288 <p>Austin Group Defect 243 is applied, adding the <b>-d</b> option and relaxing the requirement for standard input to be a text
289 file.</p>
290 <p>Austin Group Defect 367 is applied, requiring that <i>read</i> distinguishes between detecting end-of-file and an error
291 occurring, setting its exit status to one and greater than one, respectively.</p>
292 <p>Austin Group Defect 854 is applied, adding a note to the APPLICATION USAGE section that this utility is required to be
293 intrinsic.</p>
294 <p>Austin Group Defect 1122 is applied, changing the description of <i>NLSPATH .</i></p>
295 <p>Austin Group Defect 1778 is applied, clarifying how field splitting is performed.</p>
296 <p>Austin Group Defect 1779 is applied, clarifying how an error in setting any variable affects the processing of variables named
297 before or after the one generating the error.</p>
298 </blockquote>
299 <div class="box"><em>End of informative text.</em></div>
300 <hr>
301 <p> </p>
302 <a href="#top"><span class="topOfPage">return to top of page</span></a><br>
303 <hr size="2" noshade>
304 <center><font size="2">UNIX® is a registered Trademark of The Open Group.<br>
305 POSIX™ is a Trademark of The IEEE.<br>
306 Copyright © 2001-2024 The IEEE and The Open Group, All Rights Reserved<br>
307 [ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
308 "../functions/contents.html">XSH</a> | <a href="../utilities/contents.html">XCU</a> | <a href="../xrat/contents.html">XRAT</a>
309 ]</font></center>
310 <hr size="2" noshade>
311 <div class="NAVHEADER">
312 <table summary="Header navigation table" class="nav" width="100%" border="0" cellpadding="0" cellspacing="0">
313 <tr class="nav">
314 <td class="nav" width="15%" align="left" valign="bottom"><a href="../utilities/pwd.html" accesskey="P"><<<
315 Previous</a></td>
316 <td class="nav" width="70%" align="center" valign="bottom"><a href="contents.html">Home</a></td>
317 <td class="nav" width="15%" align="right" valign="bottom"><a href="../utilities/readlink.html" accesskey="N">Next
318 >>></a></td>
319 </tr>
320 </table>
321 <hr align="left" width="100%"></div>
322 </body>
323 </html>