| blob | 64f32352ee8b0c64fd1061d2571c99b1910f9d84 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
45 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
46 .\" Copyright (c) 2015, Joyent, Inc. All rights reserved.
47 .\"
48 .TH READ 2 "Jan 15, 2015"
49 .SH NAME
50 read, readv, pread, preadv \- read from file
51 .SH SYNOPSIS
52 .LP
53 .nf
54 #include <unistd.h>
56 \fBssize_t\fR \fBread\fR(\fBint\fR \fIfildes\fR, \fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fInbyte\fR);
57 .fi
59 .LP
60 .nf
61 \fBssize_t\fR \fBpread\fR(\fBint\fR \fIfildes\fR, \fBvoid *\fR\fIbuf\fR, \fBsize_t\fR \fInbyte\fR, \fBoff_t\fR \fIoffset\fR);
62 .fi
64 .LP
65 .nf
66 #include <sys/uio.h>
68 \fBssize_t\fR \fBreadv\fR(\fBint\fR \fIfildes\fR, \fBconst struct iovec *\fR\fIiov\fR, \fBint\fR \fIiovcnt\fR);
69 .fi
70 .LP
71 .nf
72 \fBssize_t\fR \fBpreadv\fR(\fBint\fR \fIfildes\fR, \fBconst struct iovec *\fR\fIiov\fR, \fBint\fR \fIiovcnt\fR, \fBoff_t\fR \fIoffset\fR);
73 .fi
76 .SH DESCRIPTION
77 .LP
78 The \fBread()\fR function attempts to read \fInbyte\fR bytes from the file
79 associated with the open file descriptor, \fIfildes\fR, into the buffer pointed
80 to by \fIbuf\fR.
81 .sp
82 .LP
83 If \fInbyte\fR is 0, \fBread()\fR returns \fB0\fR and has no other results.
84 .sp
85 .LP
86 On files that support seeking (for example, a regular file), the \fBread()\fR
87 starts at a position in the file given by the file offset associated with
88 \fIfildes\fR. The file offset is incremented by the number of bytes actually
89 read.
90 .sp
91 .LP
92 Files that do not support seeking (for example, terminals) always read from the
93 current position. The value of a file offset associated with such a file is
94 undefined.
95 .sp
96 .LP
97 If \fIfildes\fR refers to a socket, \fBread()\fR is equivalent to
98 \fBrecv\fR(3SOCKET) with no flags set.
99 .sp
100 .LP
101 No data transfer will occur past the current end-of-file. If the starting
102 position is at or after the end-of-file, \fB0\fR will be returned. If the file
103 refers to a device special file, the result of subsequent \fBread()\fR requests
104 is implementation-dependent.
105 .sp
106 .LP
107 When attempting to read from a regular file with mandatory file/record locking
108 set (see \fBchmod\fR(2)), and there is a write lock owned by another process on
109 the segment of the file to be read:
110 .RS +4
111 .TP
112 .ie t \(bu
113 .el o
114 If \fBO_NDELAY\fR or \fBO_NONBLOCK\fR is set, \fBread()\fR returns \fB\(mi1\fR
115 and sets \fBerrno\fR to \fBEAGAIN\fR.
116 .RE
117 .RS +4
118 .TP
119 .ie t \(bu
120 .el o
121 If \fBO_NDELAY\fR and \fBO_NONBLOCK\fR are clear, \fBread()\fR sleeps until the
122 blocking record lock is removed.
123 .RE
124 .sp
125 .LP
126 When attempting to read from an empty pipe (or FIFO):
127 .RS +4
128 .TP
129 .ie t \(bu
130 .el o
131 If no process has the pipe open for writing, \fBread()\fR returns \fB0\fR to
132 indicate end-of-file.
133 .RE
134 .RS +4
135 .TP
136 .ie t \(bu
137 .el o
138 If some process has the pipe open for writing and \fBO_NDELAY\fR is set,
139 \fBread()\fR returns \fB0\fR.
140 .RE
141 .RS +4
142 .TP
143 .ie t \(bu
144 .el o
145 If some process has the pipe open for writing and \fBO_NONBLOCK\fR is set,
146 \fBread()\fR returns \fB\(mi1\fR and sets \fBerrno\fR to \fBEAGAIN\fR.
147 .RE
148 .RS +4
149 .TP
150 .ie t \(bu
151 .el o
152 If \fBO_NDELAY\fR and \fBO_NONBLOCK\fR are clear, \fBread()\fR blocks until
153 data is written to the pipe or the pipe is closed by all processes that had
154 opened the pipe for writing.
155 .RE
156 .sp
157 .LP
158 When attempting to read a file associated with a terminal that has no data
159 currently available:
160 .RS +4
161 .TP
162 .ie t \(bu
163 .el o
164 If \fBO_NDELAY\fR is set, \fBread()\fR returns \fB0\fR.
165 .RE
166 .RS +4
167 .TP
168 .ie t \(bu
169 .el o
170 If \fBO_NONBLOCK\fR is set, \fBread()\fR returns \fB\(mi1\fR and sets
171 \fBerrno\fR to \fBEAGAIN\fR.
172 .RE
173 .RS +4
174 .TP
175 .ie t \(bu
176 .el o
177 If \fBO_NDELAY\fR and \fBO_NONBLOCK\fR are clear, \fBread()\fR blocks until
178 data become available.
179 .RE
180 .sp
181 .LP
182 When attempting to read a file associated with a socket or a stream that is not
183 a pipe, a FIFO, or a terminal, and the file has no data currently available:
184 .RS +4
185 .TP
186 .ie t \(bu
187 .el o
188 If \fBO_NDELAY\fR or \fBO_NONBLOCK\fR is set, \fBread()\fR returns \fB\(mi1\fR
189 and sets \fBerrno\fR to \fBEAGAIN\fR.
190 .RE
191 .RS +4
192 .TP
193 .ie t \(bu
194 .el o
195 If \fBO_NDELAY\fR and \fBO_NONBLOCK\fR are clear, \fBread()\fR blocks until
196 data becomes available.
197 .RE
198 .sp
199 .LP
200 The \fBread()\fR function reads data previously written to a file. If any
201 portion of a regular file prior to the end-of-file has not been written,
202 \fBread()\fR returns bytes with value 0. For example, \fBlseek\fR(2) allows
203 the file offset to be set beyond the end of existing data in the file. If data
204 is later written at this point, subsequent reads in the gap between the
205 previous end of data and the newly written data will return bytes with value 0
206 until data is written into the gap.
207 .sp
208 .LP
209 For regular files, no data transfer will occur past the offset maximum
210 established in the open file description associated with \fIfildes\fR.
211 .sp
212 .LP
213 Upon successful completion, where \fInbyte\fR is greater than 0, \fBread()\fR
214 will mark for update the \fBst_atime\fR field of the file, and return the
215 number of bytes read. This number will never be greater than \fInbyte\fR. The
216 value returned may be less than \fInbyte\fR if the number of bytes left in the
217 file is less than \fInbyte\fR, if the \fBread()\fR request was interrupted by a
218 signal, or if the file is a pipe or FIFO or special file and has fewer than
219 \fInbyte\fR bytes immediately available for reading. For example, a
220 \fBread()\fR from a file associated with a terminal may return one typed line
221 of data.
222 .sp
223 .LP
224 If a \fBread()\fR is interrupted by a signal before it reads any data, it will
225 return \fB\(mi1\fR with \fBerrno\fR set to \fBEINTR\fR.
226 .sp
227 .LP
228 If a \fBread()\fR is interrupted by a signal after it has successfully read
229 some data, it will return the number of bytes read.
230 .sp
231 .LP
232 A \fBread()\fR from a streams file can read data in three different modes:
233 byte-stream mode, message-nondiscard mode, and message-discard mode. The
234 default is byte-stream mode. This can be changed using the \fBI_SRDOPT\fR
235 \fBioctl\fR(2) request, and can be tested with the \fBI_GRDOPT\fR
236 \fBioctl()\fR. In byte-stream mode, \fBread()\fR retrieves data from the stream
237 until as many bytes as were requested are transferred, or until there is no
238 more data to be retrieved. Byte-stream mode ignores message boundaries.
239 .sp
240 .LP
241 In streams message-nondiscard mode, \fBread()\fR retrieves data until as many
242 bytes as were requested are transferred, or until a message boundary is
243 reached. If \fBread()\fR does not retrieve all the data in a message, the
244 remaining data is left on the stream, and can be retrieved by the next
245 \fBread()\fR call. Message-discard mode also retrieves data until as many
246 bytes as were requested are transferred, or a message boundary is reached.
247 However, unread data remaining in a message after the \fBread()\fR returns is
248 discarded, and is not available for a subsequent \fBread()\fR, \fBreadv()\fR or
249 \fBgetmsg\fR(2) call.
250 .sp
251 .LP
252 How \fBread()\fR handles zero-byte streams messages is determined by the
253 current read mode setting. In byte-stream mode, \fBread()\fR accepts data
254 until it has read \fInbyte\fR bytes, or until there is no more data to read, or
255 until a zero-byte message block is encountered. The \fBread()\fR function then
256 returns the number of bytes read, and places the zero-byte message back on the
257 stream to be retrieved by the next \fBread()\fR, \fBreadv()\fR or
258 \fBgetmsg\fR(2). In message-nondiscard mode or message-discard mode, a
259 zero-byte message returns \fB0\fR and the message is removed from the stream.
260 When a zero-byte message is read as the first message on a stream, the message
261 is removed from the stream and \fB0\fR is returned, regardless of the read
262 mode.
263 .sp
264 .LP
265 A \fBread()\fR from a streams file returns the data in the message at the front
266 of the stream head read queue, regardless of the priority band of the message.
267 .sp
268 .LP
269 By default, streams are in control-normal mode, in which a \fBread()\fR from a
270 streams file can only process messages that contain a data part but do not
271 contain a control part. The \fBread()\fR fails if a message containing a
272 control part is encountered at the stream head. This default action can be
273 changed by placing the stream in either control-data mode or control-discard
274 mode with the \fBI_SRDOPT\fR \fBioctl()\fR command. In control-data mode,
275 \fBread()\fR converts any control part to data and passes it to the application
276 before passing any data part originally present in the same message. In
277 control-discard mode, \fBread()\fR discards message control parts but returns
278 to the process any data part in the message.
279 .sp
280 .LP
281 In addition, \fBread()\fR and \fBreadv()\fR will fail if the stream head had
282 processed an asynchronous error before the call. In this case, the value of
283 \fBerrno\fR does not reflect the result of \fBread()\fR or \fBreadv()\fR but
284 reflects the prior error. If a hangup occurs on the stream being read,
285 \fBread()\fR continues to operate normally until the stream head read queue is
286 empty. Thereafter, it returns \fB0\fR.
287 .SS "\fBreadv()\fR"
288 .LP
289 The \fBreadv()\fR function is equivalent to \fBread()\fR, but places the input
290 data into the \fIiovcnt\fR buffers specified by the members of the \fIiov\fR
291 array: \fIiov\fR[\fB0\fR], \fIiov\fR[\fB1\fR], \&.\|.\|.,
292 \fIiov\fR[\fIiovcnt\fR\(mi1]. The \fIiovcnt\fR argument is valid if greater
293 than 0 and less than or equal to {\fBIOV_MAX\fR}.
294 .sp
295 .LP
296 The \fBiovec\fR structure contains the following members:
297 .sp
298 .in +2
299 .nf
300 caddr_t iov_base;
301 int iov_len;
302 .fi
303 .in -2
305 .sp
306 .LP
307 Each \fBiovec\fR entry specifies the base address and length of an area in
308 memory where data should be placed. The \fBreadv()\fR function always fills an
309 area completely before proceeding to the next.
310 .sp
311 .LP
312 Upon successful completion, \fBreadv()\fR marks for update the \fBst_atime\fR
313 field of the file.
314 .SS "\fBpread()\fR"
315 .LP
316 The \fBpread()\fR function performs the same action as \fBread()\fR, except
317 that it reads from a given position in the file without changing the file
318 pointer. The first three arguments to \fBpread()\fR are the same as
319 \fBread()\fR with the addition of a fourth argument \fIoffset\fR for the
320 desired position inside the file. \fBpread()\fR will read up to the maximum
321 offset value that can be represented in an \fBoff_t\fR for regular files. An
322 attempt to perform a \fBpread()\fR on a file that is incapable of seeking
323 results in an error.
324 .SS "\fBpreadv()\fR"
325 .LP
326 The \fBpreadv()\fR function performs the same action as \fBreadv()\fR except it
327 reads from a given position in the file without changing the file pointer. The
328 first three arguments are the same as \fBreadv()\fR with the addition of a
329 fourth argument \fIoffset\fR for the desired position inside the file.
330 \fBpreadv()\fR will read up to the maximum offset value that can be represented
331 in an \fBoff_t\fR for regular files. An attempt to perform a \fBpreadv()\fR on a
332 file that is incapable of seeking results in an error.
334 .SH RETURN VALUES
335 .LP
336 Upon successful completion, \fBread()\fR and \fBreadv()\fR return a
337 non-negative integer indicating the number of bytes actually read. Otherwise,
338 the functions return \fB\(mi1\fR and set \fBerrno\fR to indicate the error.
339 .SH ERRORS
340 .LP
341 The \fBread()\fR, \fBreadv()\fR, \fBpread()\fR, and \fBpreadv()\fR functions will fail if:
342 .sp
343 .ne 2
344 .na
345 \fB\fBEAGAIN\fR\fR
346 .ad
347 .RS 11n
348 Mandatory file/record locking was set, \fBO_NDELAY\fR or \fBO_NONBLOCK\fR was
349 set, and there was a blocking record lock; total amount of system memory
350 available when reading using raw I/O is temporarily insufficient; no data is
351 waiting to be read on a file associated with a tty device and \fBO_NONBLOCK\fR
352 was set; or no message is waiting to be read on a stream and \fBO_NDELAY\fR or
353 \fBO_NONBLOCK\fR was set.
354 .RE
356 .sp
357 .ne 2
358 .na
359 \fB\fBEBADF\fR\fR
360 .ad
361 .RS 11n
362 The \fIfildes\fR argument is not a valid file descriptor open for reading.
363 .RE
365 .sp
366 .ne 2
367 .na
368 \fB\fBEBADMSG\fR\fR
369 .ad
370 .RS 11n
371 Message waiting to be read on a stream is not a data message.
372 .RE
374 .sp
375 .ne 2
376 .na
377 \fB\fBECONNRESET\fR\fR
378 .ad
379 .RS 11n
380 The \fIfiledes\fR argument refers to a connection oriented socket and the
381 connection was forcibly closed by the peer and is no longer valid. I/O can no
382 longer be performed to \fIfiledes\fR.
383 .RE
385 .sp
386 .ne 2
387 .na
388 \fB\fBEDEADLK\fR\fR
389 .ad
390 .RS 11n
391 The read was going to go to sleep and cause a deadlock to occur.
392 .RE
394 .sp
395 .ne 2
396 .na
397 \fB\fBEINTR\fR\fR
398 .ad
399 .RS 11n
400 A signal was caught during the read operation and no data was transferred.
401 .RE
403 .sp
404 .ne 2
405 .na
406 \fB\fBEINVAL\fR\fR
407 .ad
408 .RS 11n
409 An attempt was made to read from a stream linked to a multiplexor.
410 .RE
412 .sp
413 .ne 2
414 .na
415 \fB\fBEIO\fR\fR
416 .ad
417 .RS 11n
418 A physical I/O error has occurred, or the process is in a background process
419 group and is attempting to read from its controlling terminal, and either the
420 process is ignoring or blocking the \fBSIGTTIN\fR signal or the process group
421 of the process is orphaned.
422 .RE
424 .sp
425 .ne 2
426 .na
427 \fB\fBEISDIR\fR\fR
428 .ad
429 .RS 11n
430 The \fIfildes\fR argument refers to a directory on a file system type that does
431 not support read operations on directories.
432 .RE
434 .sp
435 .ne 2
436 .na
437 \fB\fBENOLCK\fR\fR
438 .ad
439 .RS 11n
440 The system record lock table was full, so the \fBread()\fR or \fBreadv()\fR
441 could not go to sleep until the blocking record lock was removed.
442 .RE
444 .sp
445 .ne 2
446 .na
447 \fB\fBENOLINK\fR\fR
448 .ad
449 .RS 11n
450 The \fIfildes\fR argument is on a remote machine and the link to that machine
451 is no longer active.
452 .RE
454 .sp
455 .ne 2
456 .na
457 \fB\fBENXIO\fR\fR
458 .ad
459 .RS 11n
460 The device associated with \fIfildes\fR is a block special or character special
461 file and the value of the file pointer is out of range.
462 .RE
464 .sp
465 .LP
466 The \fBread()\fR and \fBpread()\fR functions will fail if:
467 .sp
468 .ne 2
469 .na
470 \fB\fBEFAULT\fR\fR
471 .ad
472 .RS 10n
473 The \fIbuf\fR argument points to an illegal address.
474 .RE
476 .sp
477 .ne 2
478 .na
479 \fB\fBEINVAL\fR\fR
480 .ad
481 .RS 10n
482 The \fInbyte\fR argument overflowed an \fBssize_t\fR.
483 .RE
485 .sp
486 .LP
487 The \fBread()\fR and \fBreadv()\fR functions will fail if:
488 .sp
489 .ne 2
490 .na
491 \fB\fBEOVERFLOW\fR\fR
492 .ad
493 .RS 13n
494 The file is a regular file, \fInbyte\fR is greater than 0, the starting
495 position is before the end-of-file, and the starting position is greater than
496 or equal to the offset maximum established in the open file description
497 associated with \fIfildes\fR.
498 .RE
500 .sp
501 .LP
502 The \fBreadv()\fR and \fBpreadv()\fR functions may fail if:
503 .sp
504 .ne 2
505 .na
506 \fB\fBEFAULT\fR\fR
507 .ad
508 .RS 10n
509 The \fIiov\fR argument points outside the allocated address space.
510 .RE
512 .sp
513 .ne 2
514 .na
515 \fB\fBEINVAL\fR\fR
516 .ad
517 .RS 10n
518 The \fIiovcnt\fR argument was less than or equal to \fB0\fR or greater than
519 {\fBIOV_MAX\fR}. See \fBIntro\fR(2) for a definition of {\fBIOV_MAX\fR}).
520 .sp
521 One of the \fBiov_len\fR values in the \fIiov\fR array was negative, or the sum
522 of the \fBiov_len\fR values in the \fIiov\fR array overflowed an \fBssize_t\fR.
523 .RE
525 .sp
526 .LP
527 The \fBpread()\fR and \fBpreadv()\fR functions will fail and the file pointer
528 remain unchanged if:
529 .sp
530 .ne 2
531 .na
532 \fB\fBESPIPE\fR\fR
533 .ad
534 .RS 10n
535 The \fIfildes\fR argument is associated with a pipe or FIFO.
536 .RE
538 .SH ATTRIBUTES
539 .LP
540 See \fBattributes\fR(5) for descriptions of the following attributes:
541 .sp
543 .sp
544 .TS
545 box;
546 c | c
547 l | l .
548 ATTRIBUTE TYPE ATTRIBUTE VALUE
549 _
550 Interface Stability Committed
551 _
552 MT-Level \fBread()\fR is Async-Signal-Safe
553 _
554 Standard See \fBstandards\fR(5).
555 .TE
557 .SH SEE ALSO
558 .LP
559 \fBIntro\fR(2), \fBchmod\fR(2), \fBcreat\fR(2), \fBdup\fR(2), \fBfcntl\fR(2),
560 \fBgetmsg\fR(2), \fBioctl\fR(2), \fBlseek\fR(2), \fBopen\fR(2), \fBpipe\fR(2),
561 \fBrecv\fR(3SOCKET), \fBattributes\fR(5), \fBstandards\fR(5),
562 \fBstreamio\fR(7I), \fBtermio\fR(7I)