mirror of https://github.com/mkerrisk/man-pages
478 lines
19 KiB
Plaintext
478 lines
19 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "READ" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" read
|
|
.SH NAME
|
|
pread, read \- read from a file
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <unistd.h>
|
|
.br
|
|
.sp
|
|
\fP
|
|
.LP
|
|
\fBssize_t pread(int\fP \fIfildes\fP\fB, void *\fP\fIbuf\fP\fB, size_t\fP
|
|
\fInbyte\fP\fB,
|
|
off_t\fP \fIoffset\fP\fB); \fP
|
|
\fB
|
|
.br
|
|
ssize_t read(int\fP \fIfildes\fP\fB, void *\fP\fIbuf\fP\fB, size_t\fP
|
|
\fInbyte\fP\fB);
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIread\fP() function shall attempt to read \fInbyte\fP bytes
|
|
from the file associated with the open file descriptor,
|
|
\fIfildes\fP, into the buffer pointed to by \fIbuf\fP. The behavior
|
|
of multiple concurrent reads on the same pipe, FIFO, or
|
|
terminal device is unspecified.
|
|
.LP
|
|
Before any action described below is taken, and if \fInbyte\fP is
|
|
zero, the \fIread\fP() function may detect and return errors
|
|
as described below. In the absence of errors, or if error detection
|
|
is not performed, the \fIread\fP() function shall return zero
|
|
and have no other results.
|
|
.LP
|
|
On files that support seeking (for example, a regular file), the \fIread\fP()
|
|
shall start at a position in the file given by
|
|
the file offset associated with \fIfildes\fP. The file offset shall
|
|
be incremented by the number of bytes actually read.
|
|
.LP
|
|
Files that do not support seeking-for example, terminals-always read
|
|
from the current position. The value of a file offset
|
|
associated with such a file is undefined.
|
|
.LP
|
|
No data transfer shall occur past the current end-of-file. If the
|
|
starting position is at or after the end-of-file, 0 shall be
|
|
returned. If the file refers to a device special file, the result
|
|
of subsequent \fIread\fP() requests is
|
|
implementation-defined.
|
|
.LP
|
|
If the value of \fInbyte\fP is greater than {SSIZE_MAX}, the result
|
|
is implementation-defined.
|
|
.LP
|
|
When attempting to read from an empty pipe or FIFO:
|
|
.IP " *" 3
|
|
If no process has the pipe open for writing, \fIread\fP() shall return
|
|
0 to indicate end-of-file.
|
|
.LP
|
|
.IP " *" 3
|
|
If some process has the pipe open for writing and O_NONBLOCK is set,
|
|
\fIread\fP() shall return -1 and set \fIerrno\fP to
|
|
[EAGAIN].
|
|
.LP
|
|
.IP " *" 3
|
|
If some process has the pipe open for writing and O_NONBLOCK is clear,
|
|
\fIread\fP() shall block the calling thread until some
|
|
data is written or the pipe is closed by all processes that had the
|
|
pipe open for writing.
|
|
.LP
|
|
.LP
|
|
When attempting to read a file (other than a pipe or FIFO) that supports
|
|
non-blocking reads and has no data currently
|
|
available:
|
|
.IP " *" 3
|
|
If O_NONBLOCK is set, \fIread\fP() shall return -1 and set \fIerrno\fP
|
|
to [EAGAIN].
|
|
.LP
|
|
.IP " *" 3
|
|
If O_NONBLOCK is clear, \fIread\fP() shall block the calling thread
|
|
until some data becomes available.
|
|
.LP
|
|
.IP " *" 3
|
|
The use of the O_NONBLOCK flag has no effect if there is some data
|
|
available.
|
|
.LP
|
|
.LP
|
|
The \fIread\fP() function reads data previously written to a file.
|
|
If any portion of a regular file prior to the end-of-file
|
|
has not been written, \fIread\fP() shall return bytes with value 0.
|
|
For example, \fIlseek\fP() allows the file offset to be set beyond
|
|
the end of existing data in the file. If data
|
|
is later written at this point, subsequent reads in the gap between
|
|
the previous end of data and the newly written data shall
|
|
return bytes with value 0 until data is written into the gap.
|
|
.LP
|
|
Upon successful completion, where \fInbyte\fP is greater than 0, \fIread\fP()
|
|
shall mark for update the \fIst_atime\fP field
|
|
of the file, and shall return the number of bytes read. This number
|
|
shall never be greater than \fInbyte\fP. The value returned
|
|
may be less than \fInbyte\fP if the number of bytes left in the file
|
|
is less than \fInbyte\fP, if the \fIread\fP() request was
|
|
interrupted by a signal, or if the file is a pipe or FIFO or special
|
|
file and has fewer than \fInbyte\fP bytes immediately
|
|
available for reading. For example, a \fIread\fP() from a file associated
|
|
with a terminal may return one typed line of data.
|
|
.LP
|
|
If a \fIread\fP() is interrupted by a signal before it reads any data,
|
|
it shall return -1 with \fIerrno\fP set to [EINTR].
|
|
.LP
|
|
If a \fIread\fP() is interrupted by a signal after it has successfully
|
|
read some data, it shall return the number of bytes
|
|
read.
|
|
.LP
|
|
For regular files, no data transfer shall occur past the offset maximum
|
|
established in the open file description associated with
|
|
\fIfildes\fP.
|
|
.LP
|
|
If \fIfildes\fP refers to a socket, \fIread\fP() shall be equivalent
|
|
to \fIrecv\fP()
|
|
with no flags set.
|
|
.LP
|
|
If the O_DSYNC and O_RSYNC bits have been set, read I/O operations
|
|
on the file descriptor shall complete as defined by synchronized
|
|
I/O data integrity completion. If the O_SYNC and O_RSYNC bits have
|
|
been set, read I/O operations on the file descriptor shall
|
|
complete as defined by synchronized I/O file integrity completion.
|
|
.LP
|
|
If \fIfildes\fP refers to a shared memory object, the result of the
|
|
\fIread\fP() function is unspecified.
|
|
.LP
|
|
If \fIfildes\fP refers to a typed memory object, the result of the
|
|
\fIread\fP() function is unspecified.
|
|
.LP
|
|
A
|
|
\fIread\fP() from a STREAMS file can read data in three different
|
|
modes: \fIbyte-stream\fP mode, \fImessage-nondiscard\fP mode,
|
|
and \fImessage-discard\fP mode. The default shall be byte-stream mode.
|
|
This can be changed using the I_SRDOPT \fIioctl\fP() request, and
|
|
can be tested with I_GRDOPT \fIioctl\fP(). In byte-stream mode, \fIread\fP()
|
|
shall retrieve data from the STREAM until as many
|
|
bytes as were requested are transferred, or until there is no more
|
|
data to be retrieved. Byte-stream mode ignores message
|
|
boundaries.
|
|
.LP
|
|
In STREAMS message-nondiscard mode, \fIread\fP() shall retrieve data
|
|
until as many bytes as were requested are transferred, or
|
|
until a message boundary is reached. If \fIread\fP() does not retrieve
|
|
all the data in a message, the remaining data shall be left
|
|
on the STREAM, and can be retrieved by the next \fIread\fP() call.
|
|
Message-discard mode also retrieves data until as many bytes as
|
|
were requested are transferred, or a message boundary is reached.
|
|
However, unread data remaining in a message after the
|
|
\fIread\fP() returns shall be discarded, and shall not be available
|
|
for a subsequent \fIread\fP(), \fIgetmsg\fP(), or \fIgetpmsg\fP()
|
|
call.
|
|
.LP
|
|
How \fIread\fP() handles zero-byte STREAMS messages is determined
|
|
by the current read mode setting. In byte-stream mode,
|
|
\fIread\fP() shall accept data until it has read \fInbyte\fP bytes,
|
|
or until there is no more data to read, or until a zero-byte
|
|
message block is encountered. The \fIread\fP() function shall then
|
|
return the number of bytes read, and place the zero-byte
|
|
message back on the STREAM to be retrieved by the next \fIread\fP(),
|
|
\fIgetmsg\fP(), or \fIgetpmsg\fP(). In message-nondiscard mode or
|
|
message-discard mode, a zero-byte message
|
|
shall return 0 and the message shall be removed from the STREAM. When
|
|
a zero-byte message is read as the first message on a STREAM,
|
|
the message shall be removed from the STREAM and 0 shall be returned,
|
|
regardless of the read mode.
|
|
.LP
|
|
A \fIread\fP() from a STREAMS file shall return the data in the message
|
|
at the front of the STREAM head read queue, regardless
|
|
of the priority band of the message.
|
|
.LP
|
|
By default, STREAMs are in control-normal mode, in which a \fIread\fP()
|
|
from a STREAMS file can only process messages that
|
|
contain a data part but do not contain a control part. The \fIread\fP()
|
|
shall fail if a message containing a control part 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 I_SRDOPT \fIioctl\fP() command. In control-data
|
|
mode,
|
|
\fIread\fP() shall convert any control part to data and pass it to
|
|
the application before passing any data part originally present
|
|
in the same message. In control-discard mode, \fIread\fP() shall discard
|
|
message control parts but return to the process any data
|
|
part in the message.
|
|
.LP
|
|
In addition, \fIread\fP() shall fail if the STREAM head had processed
|
|
an asynchronous error before the call. In this case, the
|
|
value of \fIerrno\fP shall not reflect the result of \fIread\fP(),
|
|
but reflect the prior error. If a hangup occurs on the STREAM
|
|
being read, \fIread\fP() shall continue to operate normally until
|
|
the STREAM head read queue is empty. Thereafter, it shall return
|
|
0.
|
|
.LP
|
|
The \fIpread\fP() function shall be equivalent to \fIread\fP(), except
|
|
that it shall read from a given position in the file
|
|
without changing the file pointer. The first three arguments to \fIpread\fP()
|
|
are the same as \fIread\fP() with the addition of a
|
|
fourth argument \fIoffset\fP for the desired position inside the file.
|
|
An attempt to perform a \fIpread\fP() on a file that is
|
|
incapable of seeking shall result in an error.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
Upon successful completion, \fIread\fP() \ and \fIpread\fP() shall
|
|
return a non-negative integer indicating the number of bytes actually
|
|
read. Otherwise, the
|
|
functions shall return -1 and set \fIerrno\fP to indicate the error.
|
|
.SH ERRORS
|
|
.LP
|
|
The \fIread\fP() and \fIpread\fP() functions shall fail
|
|
if:
|
|
.TP 7
|
|
.B EAGAIN
|
|
The O_NONBLOCK flag is set for the file descriptor and the process
|
|
would be delayed.
|
|
.TP 7
|
|
.B EBADF
|
|
The \fIfildes\fP argument is not a valid file descriptor open for
|
|
reading.
|
|
.TP 7
|
|
.B EBADMSG
|
|
The file is a STREAM file that is set to control-normal mode and the
|
|
message waiting to be read includes a control part.
|
|
.TP 7
|
|
.B EINTR
|
|
The read operation was terminated due to the receipt of a signal,
|
|
and no data was transferred.
|
|
.TP 7
|
|
.B EINVAL
|
|
The STREAM or multiplexer referenced by \fIfildes\fP is linked (directly
|
|
or indirectly) downstream from a multiplexer.
|
|
.TP 7
|
|
.B EIO
|
|
The process is a member of a background process attempting to read
|
|
from its controlling terminal, the process is ignoring or
|
|
blocking the SIGTTIN signal, or the process group is orphaned. This
|
|
error may also be generated for implementation-defined
|
|
reasons.
|
|
.TP 7
|
|
.B EISDIR
|
|
The \fIfildes\fP argument refers to a directory and the implementation
|
|
does not allow the directory to be read using \fIread\fP()
|
|
or \fIpread\fP(). The \fIreaddir\fP() function should be used instead.
|
|
.TP 7
|
|
.B EOVERFLOW
|
|
The file is a regular file, \fInbyte\fP is greater than 0, the starting
|
|
position is before the end-of-file, and the starting
|
|
position is greater than or equal to the offset maximum established
|
|
in the open file description associated with
|
|
\fIfildes\fP.
|
|
.sp
|
|
.LP
|
|
The \fIread\fP() function shall fail if:
|
|
.TP 7
|
|
.B EAGAIN \fRor\fP EWOULDBLOCK
|
|
.sp
|
|
The file descriptor is for a socket, is marked O_NONBLOCK, and no
|
|
data is waiting to be received.
|
|
.TP 7
|
|
.B ECONNRESET
|
|
A read was attempted on a socket and the connection was forcibly closed
|
|
by its peer.
|
|
.TP 7
|
|
.B ENOTCONN
|
|
A read was attempted on a socket that is not connected.
|
|
.TP 7
|
|
.B ETIMEDOUT
|
|
A read was attempted on a socket and a transmission timeout occurred.
|
|
.sp
|
|
.LP
|
|
The \fIread\fP() and \fIpread\fP() functions may fail
|
|
if:
|
|
.TP 7
|
|
.B EIO
|
|
A physical I/O error has occurred.
|
|
.TP 7
|
|
.B ENOBUFS
|
|
Insufficient resources were available in the system to perform the
|
|
operation.
|
|
.TP 7
|
|
.B ENOMEM
|
|
Insufficient memory was available to fulfill the request.
|
|
.TP 7
|
|
.B ENXIO
|
|
A request was made of a nonexistent device, or the request was outside
|
|
the capabilities of the device.
|
|
.sp
|
|
.LP
|
|
The \fIpread\fP() function shall fail, and the file pointer shall
|
|
remain unchanged, if:
|
|
.TP 7
|
|
.B EINVAL
|
|
The \fIoffset\fP argument is invalid. The value is negative.
|
|
.TP 7
|
|
.B EOVERFLOW
|
|
The file is a regular file and an attempt was made to read at or beyond
|
|
the offset maximum associated with the file.
|
|
.TP 7
|
|
.B ENXIO
|
|
A request was outside the capabilities of the device.
|
|
.TP 7
|
|
.B ESPIPE
|
|
\fIfildes\fP is associated with a pipe or FIFO.
|
|
.sp
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.SS Reading Data into a Buffer
|
|
.LP
|
|
The following example reads data from the file associated with the
|
|
file descriptor \fIfd\fP into the buffer pointed to by
|
|
\fIbuf\fP.
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB#include <sys/types.h>
|
|
#include <unistd.h>
|
|
\&...
|
|
char buf[20];
|
|
size_t nbytes;
|
|
ssize_t bytes_read;
|
|
int fd;
|
|
\&...
|
|
nbytes = sizeof(buf);
|
|
bytes_read = read(fd, buf, nbytes);
|
|
\&...
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
This volume of IEEE\ Std\ 1003.1-2001 does not specify the value of
|
|
the file offset after an error is returned; there
|
|
are too many cases. For programming errors, such as [EBADF], the concept
|
|
is meaningless since no file is involved. For errors that
|
|
are detected immediately, such as [EAGAIN], clearly the pointer should
|
|
not change. After an interrupt or hardware error, however,
|
|
an updated value would be very useful and is the behavior of many
|
|
implementations.
|
|
.LP
|
|
Note that a \fIread\fP() of zero bytes does not modify \fIst_atime\fP.
|
|
A \fIread\fP() that requests more than zero bytes, but
|
|
returns zero, shall modify \fIst_atime\fP.
|
|
.LP
|
|
Implementations are allowed, but not required, to perform error checking
|
|
for \fIread\fP() requests of zero bytes.
|
|
.SS Input and Output
|
|
.LP
|
|
The use of I/O with large byte counts has always presented problems.
|
|
Ideas such as \fIlread\fP() and \fIlwrite\fP() (using and
|
|
returning \fBlong\fPs) were considered at one time. The current solution
|
|
is to use abstract types on the ISO\ C standard
|
|
function to \fIread\fP() and \fIwrite\fP(). The abstract types can
|
|
be declared so that
|
|
existing functions work, but can also be declared so that larger types
|
|
can be represented in future implementations. It is presumed
|
|
that whatever constraints limit the maximum range of \fBsize_t\fP
|
|
also limit portable I/O requests to the same range. This volume
|
|
of IEEE\ Std\ 1003.1-2001 also limits the range further by requiring
|
|
that the byte count be limited so that a signed return
|
|
value remains meaningful. Since the return type is also a (signed)
|
|
abstract type, the byte count can be defined by the
|
|
implementation to be larger than an \fBint\fP can hold.
|
|
.LP
|
|
The standard developers considered adding atomicity requirements to
|
|
a pipe or FIFO, but recognized that due to the nature of
|
|
pipes and FIFOs there could be no guarantee of atomicity of reads
|
|
of {PIPE_BUF} or any other size that would be an aid to
|
|
applications portability.
|
|
.LP
|
|
This volume of IEEE\ Std\ 1003.1-2001 requires that no action be taken
|
|
for \fIread\fP() or \fIwrite\fP() when \fInbyte\fP is zero. This is
|
|
not intended to take precedence over detection of
|
|
errors (such as invalid buffer pointers or file descriptors). This
|
|
is consistent with the rest of this volume of
|
|
IEEE\ Std\ 1003.1-2001, but the phrasing here could be misread to
|
|
require detection of the zero case before any other
|
|
errors. A value of zero is to be considered a correct value, for which
|
|
the semantics are a no-op.
|
|
.LP
|
|
I/O is intended to be atomic to ordinary files and pipes and FIFOs.
|
|
Atomic means that all the bytes from a single operation that
|
|
started out together end up together, without interleaving from other
|
|
I/O operations. It is a known attribute of terminals that
|
|
this is not honored, and terminals are explicitly (and implicitly
|
|
permanently) excepted, making the behavior unspecified. The
|
|
behavior for other device types is also left unspecified, but the
|
|
wording is intended to imply that future standards might choose
|
|
to specify atomicity (or not).
|
|
.LP
|
|
There were recommendations to add format parameters to \fIread\fP()
|
|
and \fIwrite\fP() in
|
|
order to handle networked transfers among heterogeneous file system
|
|
and base hardware types. Such a facility may be required for
|
|
support by the OSI presentation of layer services. However, it was
|
|
determined that this should correspond with similar C-language
|
|
facilities, and that is beyond the scope of this volume of IEEE\ Std\ 1003.1-2001.
|
|
The concept was suggested to the
|
|
developers of the ISO\ C standard for their consideration as a possible
|
|
area for future work.
|
|
.LP
|
|
In 4.3 BSD, a \fIread\fP() or \fIwrite\fP() that is interrupted by
|
|
a signal before
|
|
transferring any data does not by default return an [EINTR] error,
|
|
but is restarted. In 4.2 BSD, 4.3 BSD, and the Eighth Edition,
|
|
there is an additional function, \fIselect\fP(), whose purpose is
|
|
to pause until specified
|
|
activity (data to read, space to write, and so on) is detected on
|
|
specified file descriptors. It is common in applications written
|
|
for those systems for \fIselect\fP() to be used before \fIread\fP()
|
|
in situations (such as
|
|
keyboard input) where interruption of I/O due to a signal is desired.
|
|
.LP
|
|
The issue of which files or file types are interruptible is considered
|
|
an implementation design issue. This is often affected
|
|
primarily by hardware and reliability issues.
|
|
.LP
|
|
There are no references to actions taken following an "unrecoverable
|
|
error". It is considered beyond the scope of this volume
|
|
of IEEE\ Std\ 1003.1-2001 to describe what happens in the case of
|
|
hardware errors.
|
|
.LP
|
|
Previous versions of IEEE\ Std\ 1003.1-2001 allowed two very different
|
|
behaviors with regard to the handling of
|
|
interrupts. In order to minimize the resulting confusion, it was decided
|
|
that IEEE\ Std\ 1003.1-2001 should support only
|
|
one of these behaviors. Historical practice on AT&T-derived systems
|
|
was to have \fIread\fP() and \fIwrite\fP() return -1 and set \fIerrno\fP
|
|
to [EINTR] when interrupted after some, but not all, of
|
|
the data requested had been transferred. However, the U.S. Department
|
|
of Commerce FIPS 151-1 and FIPS 151-2 require the historical
|
|
BSD behavior, in which \fIread\fP() and \fIwrite\fP() return the number
|
|
of bytes actually
|
|
transferred before the interrupt. If -1 is returned when any data
|
|
is transferred, it is difficult to recover from the error on a
|
|
seekable device and impossible on a non-seekable device. Most new
|
|
implementations support this behavior. The behavior required by
|
|
IEEE\ Std\ 1003.1-2001 is to return the number of bytes transferred.
|
|
.LP
|
|
IEEE\ Std\ 1003.1-2001 does not specify when an implementation that
|
|
buffers \fIread\fP()ss actually moves the data into
|
|
the user-supplied buffer, so an implementation may chose to do this
|
|
at the latest possible moment. Therefore, an interrupt arriving
|
|
earlier may not cause \fIread\fP() to return a partial byte count,
|
|
but rather to return -1 and set \fIerrno\fP to [EINTR].
|
|
.LP
|
|
Consideration was also given to combining the two previous options,
|
|
and setting \fIerrno\fP to [EINTR] while returning a short
|
|
count. However, not only is there no existing practice that implements
|
|
this, it is also contradictory to the idea that when
|
|
\fIerrno\fP is set, the function responsible shall return -1.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIfcntl\fP() , \fIioctl\fP() , \fIlseek\fP() , \fIopen\fP() , \fIpipe\fP()
|
|
, \fIreadv\fP() , the Base
|
|
Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 11, General
|
|
Terminal
|
|
Interface, \fI<stropts.h>\fP, \fI<sys/uio.h>\fP, \fI<unistd.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version 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 .
|