diff options
Diffstat (limited to 'man3p/read.3p')
| -rw-r--r-- | man3p/read.3p | 477 |
1 files changed, 477 insertions, 0 deletions
diff --git a/man3p/read.3p b/man3p/read.3p new file mode 100644 index 000000000..6322e0e3a --- /dev/null +++ b/man3p/read.3p @@ -0,0 +1,477 @@ +.\" 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 . |