'\"macro stdmacro
.if n .pH g2.read @(#)read	40.27 of 11/30/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} read 2 "" "\&"
.if \nX=1 .ds x} read 2 ""
.if \nX=2 .ds x} read 2 "" "\&"
.if \nX=3 .ds x} read "" "" "\&"
.TH \*(x}
.SH NAME
\f4read\f1 \- read from file
.SH SYNOPSIS
\f4#include <sys/types.h>\fP
.br
\f4#include <sys/uio.h>\fP
.br
\f4#include <unistd.h>\fP
.PP
\f4int read(int fildes, void \(**buf, unsigned nbyte);
.PP
\f4int readv(int fildes, struct iovec *iov, int iovcnt);\fP
.fi
.SH DESCRIPTION
\f4read\fP
attempts to read
.I nbyte\^
bytes from the file associated with
.I fildes\^
into the buffer pointed to by
.IR buf .
If \f2nbyte\f1 is zero, \f4read\fP returns zero and has no other results.
.I fildes\^
is a
file descriptor
obtained from a
\f4creat\fP,
\f4open\fP,
\f4dup\fP,
\f4fcntl\fP,
or
\f4pipe\fP
system call.
.PP
On devices capable of seeking,
the
\f4read\fP
starts at a position in the file given by the file pointer
associated with
.IR fildes .
On return from
\f4read\fP,
the file pointer is incremented by the number of bytes actually read.
.PP
Devices that are incapable of seeking always read from the current
position.
The value of a file pointer associated with such a file is undefined.
.PP
\f4readv\f1 performs the same action as \f4read\f1, but places the input data 
into the \f2iovcnt\f1 buffers specified by the members of the
\f2iov\f1
array: \f2iov\f1[0], \f2iov\f1[1], ...,
\f2iov\[\f2iovcnt\f1\-\|1].
.P
For \f4readv\f1, the \f4iovec\f1
structure contains the following members:
.P
.RS
.ft 4
.nf
addr_t    iov_base;
size_t    iov_len;
.fi
.ft 1
.RE
.P
Each \f4iovec\f1 entry specifies the base address and length of an area
in memory where data should be placed.  
\f4readv\f1 always fills one buffer completely before proceeding
to the next.
.PP
On success,
\f4read\fP and \f4readv\fP
return the number of bytes actually read and placed in the buffer;
this number may be less than
.I nbyte\^
if the file is associated with a communication line
[see
\f4ioctl\fP(2)
and
\f4termio\fP(7)],
or if the number of bytes left in the file is less than
.IR nbyte\^ ,
or if the file is a pipe or a special file.
A value of 0 is returned when an
end-of-file has been reached.
.PP
\f4read\f1 reads data previously written to a file. 
If any portion of an ordinary file prior to the end of file has not been written, 
\f4read\f1 returns the number of bytes read as \f40\f1. 
For example, the \f4lseek\f1 routine allows the file pointer to be set beyond 
the end of existing data in the file. 
If additional data is written at this point, 
subsequent reads in the gap between the previous end of data and newly written 
data return bytes with a value of \f40\f1 until data is written into the gap.
.PP
A \f4read\fP or \f4readv\fP from a \s-1STREAMS\s0 [see \f4intro\fP(2)] file can 
operate in three different modes: byte-stream mode,
message-nondiscard mode, and message-discard mode.
The default is byte-stream mode.
This can be changed using the \f4I_SRDOPT ioctl\fP(2) request
[see \f4streamio\fP(7)],
and can be tested with the \f4I_GRDOPT ioctl\f1(2) request.
In byte-stream mode, \f4read\fP and \f4readv\fP usually retrieve data from the
stream until they have retrieved \f2nbyte\f1 bytes, or
until there\p
.br
.ne 3
is no more data to be retrieved.
Byte-stream mode usually ignores message boundaries.
.PP
In \s-1STREAMS\s0 message-nondiscard mode, \f4read\fP and \f4readv\fP retrieve 
data until they have read
\f2nbyte\f1 bytes, or until they reach a message boundary.
If \f4read\fP or \f4readv\fP does not retrieve all the data in a message,
the remaining data is replaced on the stream and can be retrieved
by the next \f4read\fP or \f4readv\fP call.
Message-discard mode also retrieves data until it has retrieved
\f2nbyte\f1 bytes, or it reaches a message boundary.
However, unread data remaining in a message after the
\f4read\fP or \f4readv\fP returns is discarded, and is not available for a
subsequent \f4read\fP, \f4readv\fP, or \f4getmsg\fP [see \f4getmsg\fP(2)].
.PP
When attempting to read from a regular file with
mandatory file/record locking set [see
\f4chmod\fP(2)],
and there is a 
write lock owned by another process on the segment of the file to be read:
.IP
If
\f4O_NDELAY\fP or \f4O_NONBLOCK\fP
is set, \f4read\fP returns \-1
and sets \f4errno\fP to \f4EAGAIN\fP.
.IP
If
\f4O_NDELAY\fP and \f4O_NONBLOCK\fP
are clear, \f4read\fP sleeps until the 
blocking record lock is removed.
.PP
When attempting to read from an empty pipe (or \s-1FIFO\s0):
.IP
If no process has the pipe open for writing, \f4read\fP returns 0 to
indicate end-of-file.
.IP
If some process has the pipe open for writing and \f4O_NDELAY\fP is set, \f4read\fP 
returns 0.
.IP
If some process has the pipe open for writing and \f4O_NONBLOCK\fP is set, \f4read\fP
returns \-1 and sets \f4errno\f1 to \f4EAGAIN\fP.
.IP
If \f4O_NDELAY\fP and \f4O_NONBLOCK\fP are clear, \f4read\fP blocks until data is 
written to the pipe or the pipe is closed by all processes that had opened 
the pipe for writing.
.PP
When attempting to read a file associated with a terminal that has no data
currently available:
.IP
If
\f4O_NDELAY\fP
is set, \f4read\fP returns 0.
.IP
If
\f4O_NONBLOCK\fP
is set, \f4read\fP returns \-1 and sets \f4errno\f1 to \f4EAGAIN\fP.
.IP
If
\f4O_NDELAY\fP and \f4O_NONBLOCK\fP
are clear, \f4read\fP blocks until data becomes available.
.PP
When attempting to read a file associated with a stream that is not a pipe
or \s-1FIFO\s0, or terminal, and that has no data
currently available:
.IP
If
\f4O_NDELAY\fP or \f4O_NONBLOCK\fP
is set, \f4read\fP returns \-1 and sets \f4errno\fP to \f4EAGAIN\fP.
.IP
If
\f4O_NDELAY\fP and \f4O_NONBLOCK\fP
are clear, \f4read\fP blocks until data becomes available.
.PP
When reading from a \s-1STREAMS\s0 file, handling of zero-byte messages is
determined by the current read mode setting.
In byte-stream mode, \f4read\fP accepts data until it has read
\f2nbyte\f1 bytes, or until there is no more data 
to read, or until a zero-byte message block is encountered.
\f4read\fP
then returns the number of bytes read, and places the zero-byte
message back on the stream to be retrieved by the
next \f4read\fP or \f4getmsg\fP [see \f4getmsg\fP(2)].
In the two other modes,
a zero-byte message returns a value of 0 and the message 
is removed from the stream.
When a zero-byte message is read as the first message on a stream, a value of 0 
is returned regardless of the \f4read\fP mode.
.PP
A \f4read\fP or \f4readv\fP from a \s-1STREAMS\s0 file returns the data in the
message at the front of the stream head read queue, regardless of the priority
band of the message.
.PP
Normally, a \f4read\f1 from a \s-1STREAMS\s0 file can only process messages with 
data and without control information.
The \f4read\f1 fails if a message containing control information
is encountered at the stream head.
This default action can be changed by placing the stream in either
control-data mode or control-discard mode with the \f4I_SRDOPT ioctl\f1(2).
In control-data mode, control messages are converted to data messages
by \f4read\f1.
In control-discard mode, control messages are
discarded by \f4read\f1, but any data associated with the control
messages is returned to the user.
.PP
\f4read\fP and \f4readv\fP
fail if one or more of the following are true:
.TP 15
\f4EAGAIN\fP
Mandatory file/record locking was set,
\f4O_NDELAY\fP or \f4O_NONBLOCK\fP was set, and there was a blocking record lock.
.TP
\f4EAGAIN\fP
Total amount of system memory
available when reading via raw I/O
is temporarily insufficient.
.TP
\f4EAGAIN\fP
No data is waiting to be read on a file associated
with a tty device and \f4O_NONBLOCK\fP was set.
.TP
\f4EAGAIN\fP
No message is waiting to be read on a stream and \f4O_NDELAY\fP or \f4O_NONBLOCK\fP was set.
.TP
\f4EBADF\fP
.I fildes\^
is not a valid file descriptor open for reading.
.TP 
\f4EBADMSG\fP
Message waiting to be read on a stream is not a data message.
.TP
\f4EDEADLK\fP
The \f4read\fP was going to go to sleep
and cause a deadlock to occur.
.TP
\f4EFAULT\fP
.I buf\^
points outside the allocated address space.
.TP
\f4EINTR\fP
A signal was caught during the
\f4read\fP or \f4readv\fP
system call.
.TP
\f4EINVAL\fP
Attempted to read from a stream linked to a multiplexor.
.TP
\f4EIO\fP
A physical I/O error has occurred, or the process is in a background
process group and is attempting to read from its controlling
terminal, and either the process is ignoring or blocking the
\f4SIGTTIN\fP signal or the process group of the process is
orphaned.
.TP
\f4ENOLCK\fP
The system record lock table was full,
so the \f4read\fP or \f4readv\fP could not go to sleep until
the blocking record lock was removed.
.TP
\f4ENOLINK\fP
\f2fildes\f1 is on a remote machine and the link 
to that machine is no longer active.
.TP
\f4ENXIO\fP
The device associated with \f2fildes\fP is a block special or
character special file and the value of the file pointer is
out of range.
.PP
In addition, \f4readv\fP may return one of the following errors:
.TP 15
\f4EFAULT\fP
\f2iov\f1 points outside the allocated address space.
.TP
\f4EINVAL\f1
\f2iovcnt\fP was less than or equal to 0 or greater than 16.
.TP
\f4EINVAL\f1
The sum of the \f4iov_len\fP values in the \f2iov\f1 array overflowed
a 32-bit integer.
.PP
A \f4read\fP from a \s-1STREAMS\s0 file also fails if an error message is received
at the stream head.
In this case, \f4errno\f1 is set to the value returned in the
error message.
If a hangup occurs on the stream being read,
\f4read\fP continues to operate normally until the stream head read queue 
is empty.
Thereafter, it returns 0.
.SH "SEE ALSO"
\f4intro\fP(2), \f4creat\fP(2), \f4dup\fP(2), \f4fcntl\fP(2), \f4getmsg\fP(2),
\f4ioctl\fP(2), \f4open\fP(2), \f4pipe\fP(2)
.sp .2
\f4streamio\fP(7), \f4termio\fP(7) in the \f2System Administrator's Reference Manual\f1
.SH "DIAGNOSTICS"
On success a non-negative integer is returned
indicating the number of bytes actually read.
Otherwise, a \-1 is returned and \f4errno\fP
is set to indicate the error.
.\"	@(#)read.2	6.2 of 9/6/83
.Ee
