| 1 | .\" Copyright (c) 1980 Regents of the University of California.
|
|---|
| 2 | .\" All rights reserved. The Berkeley software License Agreement
|
|---|
| 3 | .\" specifies the terms and conditions for redistribution.
|
|---|
| 4 | .\"
|
|---|
| 5 | .\" @(#)read.2 6.6 (Berkeley) 5/23/86
|
|---|
| 6 | .\"
|
|---|
| 7 | .TH READ 2 "May 23, 1986"
|
|---|
| 8 | .UC 4
|
|---|
| 9 | .SH NAME
|
|---|
| 10 | read \- read input
|
|---|
| 11 | .SH SYNOPSIS
|
|---|
| 12 | .nf
|
|---|
| 13 | .ft B
|
|---|
| 14 | #include <sys/types.h>
|
|---|
| 15 | #include <unistd.h>
|
|---|
| 16 |
|
|---|
| 17 | ssize_t read(int \fId\fP, void *\fIbuf\fP, size_t \fInbytes\fP)
|
|---|
| 18 | .fi
|
|---|
| 19 | .SH DESCRIPTION
|
|---|
| 20 | .B Read
|
|---|
| 21 | attempts to read
|
|---|
| 22 | .I nbytes
|
|---|
| 23 | of data from the object referenced by the descriptor
|
|---|
| 24 | .I d
|
|---|
| 25 | into the buffer pointed to by
|
|---|
| 26 | .IR buf .
|
|---|
| 27 | .PP
|
|---|
| 28 | On objects capable of seeking, the
|
|---|
| 29 | .B read
|
|---|
| 30 | starts at a position
|
|---|
| 31 | given by the pointer associated with
|
|---|
| 32 | .IR d
|
|---|
| 33 | (see
|
|---|
| 34 | .BR lseek (2)).
|
|---|
| 35 | Upon return from
|
|---|
| 36 | .BR read ,
|
|---|
| 37 | the pointer is incremented by the number of bytes actually read.
|
|---|
| 38 | .PP
|
|---|
| 39 | Objects that are not capable of seeking always read from the current
|
|---|
| 40 | position. The value of the pointer associated with such an
|
|---|
| 41 | object is undefined.
|
|---|
| 42 | .PP
|
|---|
| 43 | Upon successful completion,
|
|---|
| 44 | .B read
|
|---|
| 45 | return the number of bytes actually read and placed in the buffer.
|
|---|
| 46 | The system guarantees to read the number of bytes requested if
|
|---|
| 47 | the descriptor references a normal file that has that many bytes left
|
|---|
| 48 | before the end-of-file, but in no other case.
|
|---|
| 49 | .PP
|
|---|
| 50 | If the returned value is 0, then
|
|---|
| 51 | end-of-file has been reached.
|
|---|
| 52 | .SH "RETURN VALUE
|
|---|
| 53 | If successful, the
|
|---|
| 54 | number of bytes actually read is returned.
|
|---|
| 55 | Otherwise, a \-1 is returned and the global variable
|
|---|
| 56 | .B errno
|
|---|
| 57 | is set to indicate the error.
|
|---|
| 58 | .SH "ERRORS
|
|---|
| 59 | .B Read
|
|---|
| 60 | will fail if one or more of the following are true:
|
|---|
| 61 | .TP 15
|
|---|
| 62 | [EBADF]
|
|---|
| 63 | \fID\fP is not a valid descriptor open for reading.
|
|---|
| 64 | .TP 15
|
|---|
| 65 | [EFAULT]
|
|---|
| 66 | \fIBuf\fP points outside the allocated address space.
|
|---|
| 67 | .TP 15
|
|---|
| 68 | [EIO]
|
|---|
| 69 | An I/O error occurred while reading from the file system.
|
|---|
| 70 | .TP 15
|
|---|
| 71 | [EINTR]
|
|---|
| 72 | A read from a slow device was interrupted before
|
|---|
| 73 | any data arrived by the delivery of a signal.
|
|---|
| 74 | .TP 15
|
|---|
| 75 | [EAGAIN]
|
|---|
| 76 | The file was marked for non-blocking I/O,
|
|---|
| 77 | and no data were ready to be read.
|
|---|
| 78 | .SH "SEE ALSO"
|
|---|
| 79 | .BR dup (2),
|
|---|
| 80 | .BR fcntl (2),
|
|---|
| 81 | .BR open (2),
|
|---|
| 82 | .BR pipe (2),
|
|---|
| 83 | .BR write (2).
|
|---|
