| blob | ec5a1a8797bafc543be31d812803ba19ed89c625 |
1 '\" te
2 .\" Copyright (c) 1992, X/Open Company Limited All Rights Reserved
3 .\" Copyright 1989 AT&T
4 .\" Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved
5 .\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
6 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
7 .\" http://www.opengroup.org/bookstore/.
8 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
9 .\" This notice shall appear on any product containing this material.
10 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
11 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
12 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
13 .TH READ 1 "Dec 18, 2007"
14 .SH NAME
15 read \- read a line from standard input
16 .SH SYNOPSIS
17 .LP
18 .nf
19 \fB/usr/bin/read\fR [\fB-r\fR] \fIvar\fR...
20 .fi
22 .SS "sh"
23 .LP
24 .nf
25 \fBread\fR \fIname\fR...
26 .fi
28 .SS "csh"
29 .LP
30 .nf
31 \fBset\fR \fIvariable\fR= $<
32 .fi
34 .SS "ksh"
35 .LP
36 .nf
37 \fBread\fR [\fB-prsu\fR [\fIn\fR]] [\fIname\fR ? \fIprompt\fR] [\fIname\fR]...
38 .fi
40 .SS "ksh93"
41 .LP
42 .nf
43 \fBread\fR [\fB-Aprs\fR] [\fB-d\fR \fIdelim\fR] [\fB-n\fR \fInsize\fR] [\fB-N\fR \fInsize\fR] [\fB-t\fR \fItimeout\fR][\fB-u\fR \fIunit\fR] [\fIvname\fR\fB?\fR\fIprompt\fR] [\fIvname\fR... ]
44 .fi
46 .SH DESCRIPTION
47 .SS "/usr/bin/read"
48 .sp
49 .LP
50 The \fBread\fR utility reads a single line from standard input.
51 .sp
52 .LP
53 By default, unless the \fB-r\fR option is specified, backslash (\fB\e\fR) acts
54 as an escape character. If standard input is a terminal device and the invoking
55 shell is interactive, \fBread\fR prompts for a continuation line when:
56 .RS +4
57 .TP
58 .ie t \(bu
59 .el o
60 The shell reads an input line ending with a backslash, unless the \fB-r\fR
61 option is specified.
62 .RE
63 .RS +4
64 .TP
65 .ie t \(bu
66 .el o
67 A here-document is not terminated after a \fBNEWLINE\fR character is entered.
68 .RE
69 .sp
70 .LP
71 The line is split into fields as in the shell. The first field is assigned to
72 the first variable \fIvar\fR, the second field to the second variable
73 \fIvar\fR, and so forth. If there are fewer \fIvar\fR operands specified than
74 there are fields, the leftover fields and their intervening separators is
75 assigned to the last \fIvar\fR. If there are fewer fields than \fIvar\fRs, the
76 remaining \fIvar\fRs is set to empty strings.
77 .sp
78 .LP
79 The setting of variables specified by the \fIvar\fR operands affects the
80 current shell execution environment. If it is called in a sub-shell or separate
81 utility execution environment, such as one of the following:
82 .sp
83 .in +2
84 .nf
85 \fB(read foo)
86 nohup read ...
87 find . -exec read ... \e;\fR
88 .fi
89 .in -2
90 .sp
92 .sp
93 .LP
94 it does not affect the shell variables in the caller's environment.
95 .sp
96 .LP
97 The standard input must be a text file.
98 .SS "sh"
99 .sp
100 .LP
101 One line is read from the standard input and, using the internal field
102 separator, \fBIFS\fR (normally space or tab), to delimit word boundaries, the
103 first word is assigned to the first \fIname\fR, the second word to the second
104 \fIname\fR, and so on, with leftover words assigned to the last \fIname\fR.
105 Lines can be continued using \fB\enewline\fR\&. Characters other than
106 \fBNEWLINE\fR can be quoted by preceding them with a backslash. These
107 backslashes are removed before words are assigned to \fInames\fR, and no
108 interpretation is done on the character that follows the backslash. The return
109 code is \fB0\fR, unless an end-of-file is encountered.
110 .SS "csh"
111 .sp
112 .LP
113 The notation:
114 .sp
115 .in +2
116 .nf
117 set \fIvariable\fR \fB= $<\fR
118 .fi
119 .in -2
120 .sp
122 .sp
123 .LP
124 loads one line of standard input as the value for \fIvariable\fR. (See
125 \fBcsh\fR(1)).
126 .SS "ksh"
127 .sp
128 .LP
129 The shell input mechanism. One line is read and is broken up into fields using
130 the characters in \fBIFS\fR as separators. The escape character, \fB(\e)\fR, is
131 used to remove any special meaning for the next character and for line
132 continuation. In raw mode, the \fB-r\fR, the \fB,\fR and the \fB\e\fR character
133 are not treated specially. The first field is assigned to the first \fIname\fR,
134 the second field to the second \fIname\fR, and so on, with leftover fields
135 assigned to the last \fIname\fR. The \fB-p\fR option causes the input line to
136 be taken from the input pipe of a process spawned by the shell using \fB|&\fR.
137 If the \fB-s\fR flag is present, the input is saved as a command in the history
138 file. The flag \fB-u\fR can be used to specify a one digit file descriptor unit
139 \fIn\fR to read from. The file descriptor can be opened with the \fBexec\fR
140 special command. The default value of \fIn\fR is \fB0\fR. If \fIname\fR is
141 omitted, \fBREPLY\fR is used as the default \fIname\fR. The exit status is
142 \fB0\fR unless the input file is not open for reading or an end-of-file is
143 encountered. An end-of-file with the \fB-p\fR option causes cleanup for this
144 process so that another can be spawned. If the first argument contains a
145 \fB?\fR, the remainder of this word is used as a \fIprompt\fR on standard error
146 when the shell is interactive. The exit status is \fB0\fR unless an end-of-file
147 is encountered.
148 .SS "ksh93"
149 .sp
150 .LP
151 \fBread\fR reads a line from standard input and breaks it into fields using the
152 characters in the value of the \fBIFS\fR variable as separators. The escape
153 character, \fB\e\fR, is used to remove any special meaning for the next
154 character and for line continuation unless the \fB-r\fR option is specified.
155 .sp
156 .LP
157 If there are more variables than fields, the remaining variables are set to
158 empty strings. If there are fewer variables than fields, the leftover fields
159 and their intervening separators are assigned to the last variable. If no
160 \fIvar\fR is specified, the variable \fBREPLY\fR is used.
161 .sp
162 .LP
163 When \fIvar\fR has the binary attribute and \fB-n\fR or \fB-N\fR is specified,
164 the bytes that are read are stored directly into \fIvar\fR.
165 .sp
166 .LP
167 If you specify \fB?\fR\fIprompt\fR after the first \fIvar\fR, \fBread\fR
168 displays a prompt on standard error when standard input is a terminal or pipe.
169 .SH OPTIONS
170 .SS "/usr/bin/read, ksh"
171 .sp
172 .LP
173 The following option is supported by \fB/usr/bin/read\fR and \fBksh\fR:
174 .sp
175 .ne 2
176 .na
177 \fB\fB-r\fR\fR
178 .ad
179 .RS 6n
180 Do not treat a backslash character in any special way. Considers each backslash
181 to be part of the input line.
182 .RE
184 .SS "ksh93"
185 .sp
186 .LP
187 The following options are supported by \fBksh93\fR:
188 .sp
189 .ne 2
190 .na
191 \fB\fB-A\fR\fR
192 .ad
193 .RS 14n
194 Unset \fIvar\fR, and create an indexed array containing each field in the line
195 starting at index \fB0\fR.
196 .RE
198 .sp
199 .ne 2
200 .na
201 \fB\fB-d\fR \fIdelim\fR\fR
202 .ad
203 .RS 14n
204 Read until delimiter \fIdelim\fR instead of to the end of line.
205 .RE
207 .sp
208 .ne 2
209 .na
210 \fB\fB-n\fR \fInsize\fR\fR
211 .ad
212 .RS 14n
213 Read at most \fInsize\fR bytes. Binary field size is in bytes.
214 .RE
216 .sp
217 .ne 2
218 .na
219 \fB\fB-N\fR \fInsize\fR\fR
220 .ad
221 .RS 14n
222 Read exactly \fInsize\fR bytes. Binary field size is in bytes.
223 .RE
225 .sp
226 .ne 2
227 .na
228 \fB\fB-p\fR\fR
229 .ad
230 .RS 14n
231 Read from the current co-process instead of standard input. An end of file
232 causes \fBread\fR to disconnect the co-process so that another can be created.
233 .RE
235 .sp
236 .ne 2
237 .na
238 \fB\fB-r\fR\fR
239 .ad
240 .RS 14n
241 Do not treat \fB\e\fR specially when processing the input line.
242 .RE
244 .sp
245 .ne 2
246 .na
247 \fB\fB-s\fR\fR
248 .ad
249 .RS 14n
250 Save a copy of the input as an entry in the shell history file.
251 .RE
253 .sp
254 .ne 2
255 .na
256 \fB\fB-t\fR \fItimeout\fR\fR
257 .ad
258 .RS 14n
259 Specify a \fItimeout\fR in seconds when reading from a terminal or pipe.
260 .RE
262 .sp
263 .ne 2
264 .na
265 \fB\fB-u\fR \fIfd\fR\fR
266 .ad
267 .RS 14n
268 Read from file descriptor number \fIfd\fR instead of standard input. The
269 default value is \fB0\fR.
270 .RE
272 .sp
273 .ne 2
274 .na
275 \fB\fB-v\fR\fR
276 .ad
277 .RS 14n
278 When reading from a terminal, display the value of the first variable and use
279 it as a default value.
280 .RE
282 .SH OPERANDS
283 .sp
284 .LP
285 The following operand is supported:
286 .sp
287 .ne 2
288 .na
289 \fB\fIvar\fR\fR
290 .ad
291 .RS 7n
292 The name of an existing or non-existing shell variable.
293 .RE
295 .SH EXAMPLES
296 .LP
297 \fBExample 1 \fRUsing the \fBread\fR Command
298 .sp
299 .LP
300 The following example for \fB/usr/bin/read\fR prints a file with the first
301 field of each line moved to the end of the line:
303 .sp
304 .in +2
305 .nf
306 example% \fBwhile read -r xx yy
307 do
308 printf "%s %s\en" "$yy" "$xx"
309 done < input_file\fR
310 .fi
311 .in -2
312 .sp
314 .SH ENVIRONMENT VARIABLES
315 .sp
316 .LP
317 See \fBenviron\fR(5) for descriptions of the following environment variables
318 that affect the execution of \fBread\fR: \fBLANG\fR, \fBLC_ALL\fR,
319 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
320 .sp
321 .ne 2
322 .na
323 \fB\fBIFS\fR\fR
324 .ad
325 .RS 7n
326 Determines the internal field separators used to delimit fields.
327 .RE
329 .sp
330 .ne 2
331 .na
332 \fB\fBPS2\fR\fR
333 .ad
334 .RS 7n
335 Provides the prompt string that an interactive shell writes to standard error
336 when a line ending with a backslash is read and the \fB-r\fR option was not
337 specified, or if a here-document is not terminated after a NEWLINE character is
338 entered.
339 .RE
341 .SH EXIT STATUS
342 .sp
343 .LP
344 The following exit values are returned:
345 .sp
346 .ne 2
347 .na
348 \fB\fB0\fR\fR
349 .ad
350 .RS 6n
351 Successful completion.
352 .RE
354 .sp
355 .ne 2
356 .na
357 \fB\fB>0\fR\fR
358 .ad
359 .RS 6n
360 End-of-file was detected or an error occurred.
361 .RE
363 .SH ATTRIBUTES
364 .sp
365 .LP
366 See \fBattributes\fR(5) for descriptions of the following attributes:
367 .SS "/usr/bin/read, csh, ksh, sh"
368 .sp
370 .sp
371 .TS
372 box;
373 c | c
374 l | l .
375 ATTRIBUTE TYPE ATTRIBUTE VALUE
376 _
377 Interface Stability Committed
378 _
379 Standard See \fBstandards\fR(5).
380 .TE
382 .SS "ksh93"
383 .sp
385 .sp
386 .TS
387 box;
388 c | c
389 l | l .
390 ATTRIBUTE TYPE ATTRIBUTE VALUE
391 _
392 Interface Stability Uncommitted
393 .TE
395 .SH SEE ALSO
396 .sp
397 .LP
398 \fBcsh\fR(1), \fBksh\fR(1), \fBksh93\fR(1), \fBline\fR(1), \fBset\fR(1),
399 \fBsh\fR(1), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)