406 lines
13 KiB
Groff
406 lines
13 KiB
Groff
'\"macro stdmacro
|
|
.if n .pH g2.read @(#)read 41.7 of 5/26/91
|
|
.\" Copyright 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1989, 1990 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, \f4readv\f1, \f4pread\f1, \f4pread64\f1 \- read from file
|
|
.SH SYNOPSIS
|
|
\f4#include <unistd.h>\fP
|
|
.br
|
|
\f4ssize_t read(int fildes, void \(**buf, size_t nbyte);\fP
|
|
.br
|
|
\f4ssize_t pread(int fildes, void \(**buf, size_t nbyte, off_t offset);\fP
|
|
.br
|
|
\f4ssize_t pread64(int fildes, void \(**buf, size_t nbyte, off64_t offset);\fP
|
|
.PP
|
|
\f4#include <sys/uio.h>\fP
|
|
.br
|
|
\f4ssize_t readv(int fildes, const 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\fP 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,
|
|
\f4pipe\fP,
|
|
or
|
|
\f4ioctl\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
|
|
\f4pread\fP and \f4pread64\fP are the same as \f4read\fP except that
|
|
they do the equivalent of an \f4lseek\fP (for \f4pread\fP) or
|
|
\f4lseek64\fP (for \f4pread64\fP)
|
|
.I offset
|
|
bytes with the
|
|
.I whence
|
|
set to \f4SEEK_SET\fP
|
|
before reading.
|
|
On return from
|
|
\f4pread\fP or \f4pread64\fP,
|
|
the file pointer is unchanged. If \f4fildes\fP refers to a file
|
|
incapable of seeking (a fifo or socket) then an error is returned and
|
|
\f4errno\fP will be set to \f4ESPIPE\fP.
|
|
.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
|
|
void \(**iov_base;
|
|
ssize_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;
|
|
There are many possible reasons why this number may be less than
|
|
.I nbyte\^ ,
|
|
without indicating end-of-file or an error.
|
|
Some common reasons include
|
|
when the file is associated with a communication line
|
|
[see
|
|
\f4ioctl\fP(2)
|
|
and
|
|
\f4termio\fP(7)],
|
|
or when the number of bytes left in the file is less than
|
|
.IR nbyte\^ ,
|
|
or when the file is a pipe or a special file,
|
|
or the system call was interrupted.
|
|
When end-of-file has been reached, read will return a value
|
|
of 0. A value greater than 0, but less than
|
|
.I nbyte\^ ,
|
|
should not be construed as implying end-of-file, because many
|
|
devices and even filesystems can return short counts for various
|
|
reasons.
|
|
.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
|
|
When attempting to \f4read\fP from a file with \f4O_DIRECT\fP or \f4FDIRECT\fP
|
|
set, \-1 will be returned and \f4errno\fP will be set to \f4EINVAL\fP if
|
|
\f4nbyte\fP or the current file position is not a multiple of the underlying
|
|
device's blocksize, \f2nbyte\fP is too big or \f2buf\fP isn't properly aligned.
|
|
See also \f4F_DIOINFO\fP in the \f4fcntl\fP(2) manual entry.
|
|
.PP
|
|
When attempting to \f4read\fP from a file with \f4O_RSYNC\fP and
|
|
\f4O_SYNC\fP set, the read will will wait to return until both the
|
|
file data and file status to be physically updated.
|
|
When attempting to \f4read\fP from a file with \f4O_RSYNC\fP and
|
|
\f4O_DSYNC\fP set, the read will will wait to return until the
|
|
file data has been physically updated.
|
|
.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 or slave pty
|
|
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 master pty or any other
|
|
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 attempting to read from a regular file
|
|
in a DMAPI file system, if the DMAPI application will take
|
|
a considerable time to make the file data 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 sleeps until the
|
|
the DMAPI application has made the file data 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
|
|
\f4EACCES\fP
|
|
\f2fildes\fP is open to a dynamic device and read permission is denied.
|
|
.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
|
|
\f4EAGAIN\fP
|
|
A DMAPI application might delay a considerable time retrieving the file data,
|
|
and \f4O_NDELAY\fP or \f4O_NONBLOCK\fP was set.
|
|
.TP
|
|
\f4EBADF\fP
|
|
\f2fildes\fP
|
|
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 and no bytes had been read.
|
|
.TP
|
|
\f4EINVAL\fP
|
|
Attempted to read from a stream linked to a multiplexor.
|
|
.TP
|
|
\f4EINVAL\f1
|
|
\f2fildes\fP has \f4O_DIRECT\fP or \f4FDIRECT\fP set and either the buffer
|
|
alignment, current file pointer alignment or read request size is
|
|
not valid for direct I/O.
|
|
See also \f4F_DIOINFO\fP on \f4fcntl\fP(2).
|
|
.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
|
|
\f4EIO\fP
|
|
\f2fildes\fP is open to a device that is in the process of closing.
|
|
.TP
|
|
\f4EIO\fP
|
|
\f2fildes\fP has \f4O_DIRECT\fP or \f4FDIRECT\fP set and the number of
|
|
bytes requested by \f4read\fP or \f4readv\fP is greater than the number
|
|
of bytes between the current file pointer position and end of file.
|
|
.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.
|
|
.TP
|
|
\f4ESPIPE\f1
|
|
\f2pread\fP or \f2pread64\fP was called on a file incapable of seeking.
|
|
.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 \f4{IOV_MAX}\fP.
|
|
\f4{IOV_MAX}\fP is the maximum number of \f4iovec\fP structures that one
|
|
process has available for use with \f4readv\fP.
|
|
The value \f4{IOV_MAX}\fP can be obtained from a call to \f4sysconf\fP()
|
|
[see \f4sysconf\fP(3C)].
|
|
.TP
|
|
\f4EINVAL\f1
|
|
The sum of the \f4iov_len\fP values in the \f2iov\f1 array overflowed
|
|
a 32-bit integer.
|
|
.TP
|
|
\f4ETIMEDOUT\fP
|
|
The object of the read is located on a remote system which is not available [see \f4intro\fP(2)].
|
|
.TP
|
|
.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),
|
|
\f4recv\fP(3N), \f4streamio\fP(7), \f4sysconf\fP(3C), \f4termio\fP(7),
|
|
\f4pty\fP(7M).
|
|
.SH NOTES
|
|
\f4read\fP updates the time of last access (see \f4stat\fP(2)) of the
|
|
file.
|
|
.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
|