Reading to the End of a File in C
IEEE Std 1003.1, 2004 Edition
Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved.
Proper noun
pread, read - read from a file
SYNOPSIS
#include <unistd.h>
[XSI]ssize_t pread(int fildes , void * buf , size_t nbyte , off_t offset );
![[Option End]](https://pubs.opengroup.org/onlinepubs/009604599/functions/../images/opt-end.gif)
ssize_t read(int fildes , void * buf , size_t nbyte );
Clarification
The read() function shall try to read nbyte bytes from the file associated with the open file descriptor, fildes, into the buffer pointed to past buf. The behavior of multiple concurrent reads on the aforementioned piping, FIFO, or terminal device is unspecified.
Before any action described beneath is taken, and if nbyte is cipher, the read() function may find and return errors as described beneath. In the absence of errors, or if fault detection is non performed, the read() function shall return nada and have no other results.
On files that support seeking (for instance, a regular file), the read() shall start at a position in the file given by the file offset associated with fildes. The file commencement shall exist incremented by the number of bytes actually read.
Files that practice non support seeking-for example, terminals-e'er read from the current position. The value of a file offset associated with such a file is undefined.
No data transfer shall occur past the electric current end-of-file. If the starting position is at or afterward the finish-of-file, 0 shall be returned. If the file refers to a device special file, the effect of subsequent read() requests is implementation-divers.
If the value of nbyte is greater than {SSIZE_MAX}, the result is implementation-defined.
When attempting to read from an empty piping or FIFO:
If no process has the piping open for writing, read() shall return 0 to indicate end-of-file.
If some process has the pipe open for writing and O_NONBLOCK is ready, read() shall return -1 and set errno to [EAGAIN].
If some process has the pipage open for writing and O_NONBLOCK is clear, read() shall block the calling thread until some data is written or the pipe is closed past all processes that had the pipe open for writing.
When attempting to read a file (other than a piping or FIFO) that supports non-blocking reads and has no data currently bachelor:
If O_NONBLOCK is set, read() shall return -1 and set errno to [EAGAIN].
If O_NONBLOCK is clear, read() shall cake the calling thread until some data becomes available.
The use of the O_NONBLOCK flag has no effect if there is some data available.
The read() function reads data previously written to a file. If whatsoever portion of a regular file prior to the end-of-file has non been written, read() shall return bytes with value 0. For instance, lseek() allows the file beginning to exist set up beyond the end of existing data in the file. If data is later written at this betoken, subsequent reads in the gap between the previous end of information and the newly written data shall return bytes with value 0 until data is written into the gap.
Upon successful completion, where nbyte is greater than 0, read() shall mark for update the st_atime field of the file, and shall return the number of bytes read. This number shall never exist greater than nbyte. The value returned may be less than nbyte if the number of bytes left in the file is less than nbyte, if the read() request was interrupted by a indicate, or if the file is a pipe or FIFO or special file and has fewer than nbyte bytes immediately available for reading. For example, a read() from a file associated with a terminal may return one typed line of data.
If a read() is interrupted by a signal earlier it reads any data, it shall render -ane with errno fix to [EINTR].
If a read() is interrupted by a signal after it has successfully read some data, it shall return the number of bytes read.
For regular files, no data transfer shall occur past the beginning maximum established in the open file description associated with fildes.
If fildes refers to a socket, read() shall be equivalent to recv() with no flags set up.
[SIO]
[SHM]
[TYM]
[XSR]
In STREAMS message-nondiscard way, read() shall retrieve data until equally many bytes every bit were requested are transferred, or until a bulletin boundary is reached. If read() does not retrieve all the data in a bulletin, the remaining data shall be left on the STREAM, and can be retrieved by the next read() call. Bulletin-discard style also retrieves data until every bit many bytes equally were requested are transferred, or a message boundary is reached. However, unread data remaining in a bulletin afterwards the read() returns shall be discarded, and shall not be available for a subsequent read(), getmsg(), or getpmsg() call.
How read() handles nada-byte STREAMS messages is adamant past the current read mode setting. In byte-stream style, read() shall accept data until it has read nbyte bytes, or until there is no more than data to read, or until a nil-byte message cake is encountered. The read() function shall then return the number of bytes read, and place the nix-byte message back on the STREAM to be retrieved by the next read(), getmsg(), or getpmsg(). In message-nondiscard way or message-discard fashion, a zero-byte message shall return 0 and the message shall be removed from the STREAM. When a zero-byte message is read equally the first bulletin on a STREAM, the message shall be removed from the STREAM and 0 shall be returned, regardless of the read mode.
A read() from a STREAMS file shall return the information in the bulletin at the forepart of the STREAM caput read queue, regardless of the priority ring of the message.
By default, STREAMs are in command-normal fashion, in which a read() from a STREAMS file tin can only process messages that contain a data role but do not incorporate a control part. The read() shall fail if a message containing a command part is encountered at the STREAM head. This default action tin be inverse past placing the STREAM in either control-data fashion or control-discard mode with the I_SRDOPT ioctl() command. In control-information mode, read() shall catechumen whatever control part to information and pass it to the application before passing any data part originally present in the same message. In control-discard way, read() shall discard message command parts but render to the process whatsoever data part in the message.
In addition, read() shall neglect if the STREAM head had processed an asynchronous error earlier the telephone call. In this case, the value of errno shall not reflect the result of read(), simply reflect the prior error. If a hangup occurs on the STREAM being read, read() shall continue to operate normally until the STREAM head read queue is empty. Thereafter, it shall return 0.
[XSI]
RETURN VALUE
Upon successful completion, read() [XSI]
ERRORS
The read() and [XSI]
- [EAGAIN]
- The O_NONBLOCK flag is ready for the file descriptor and the thread would be delayed.
- [EBADF]
- The fildes argument is not a valid file descriptor open for reading.
- [EBADMSG]
- [XSR]
- [EINTR]
- The read operation was terminated due to the receipt of a bespeak, and no data was transferred.
- [EINVAL]
- [XSR]
- [EIO]
- The process is a fellow member of a background procedure attempting to read from its controlling last, the procedure is ignoring or blocking the SIGTTIN bespeak, or the process group is orphaned. This error may also be generated for implementation-divers reasons.
- [EISDIR]
- [XSI]
- [EOVERFLOW]
- The file is a regular file, nbyte is greater than 0, the starting position is earlier 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 fildes.
The read() function shall fail if:
- [EAGAIN] or [EWOULDBLOCK]
- The file descriptor is for a socket, is marked O_NONBLOCK, and no data is waiting to be received.
- [ECONNRESET]
- A read was attempted on a socket and the connection was forcibly closed by its peer.
- [ENOTCONN]
- A read was attempted on a socket that is not continued.
- [ETIMEDOUT]
- A read was attempted on a socket and a transmission timeout occurred.
The read() and [XSI]
- [EIO]
- A concrete I/O mistake has occurred.
- [ENOBUFS]
- Bereft resource were available in the system to perform the operation.
- [ENOMEM]
- Insufficient retentiveness was available to fulfill the request.
- [ENXIO]
- A asking was made of a nonexistent device, or the request was outside the capabilities of the device.
The pread() role shall fail, and the file pointer shall remain unchanged, if:
- [EINVAL]
- [XSI]
- [EOVERFLOW]
- [XSI]
- [ENXIO]
- [XSI]
- [ESPIPE]
- [XSI]
The following sections are informative.
EXAMPLES
Reading Data into a Buffer
The post-obit example reads data from the file associated with the file descriptor fd into the buffer pointed to by buf.
#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); ...
Awarding USAGE
None.
RATIONALE
This volume of IEEE Std 1003.ane-2001 does not specify the value of the file offset afterwards an mistake is returned; at that place 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 every bit [EAGAIN], clearly the pointer should not change. After an interrupt or hardware fault, however, an updated value would be very useful and is the behavior of many implementations.
Note that a read() of zip bytes does non modify st_atime. A read() that requests more than nothing bytes, but returns zero, shall change st_atime.
Implementations are immune, but not required, to perform error checking for read() requests of cipher bytes.
Input and Output
The use of I/O with large byte counts has always presented problems. Ideas such as lread() and lwrite() (using and returning longsouthward) were considered at ane time. The electric current solution is to apply abstract types on the ISO C standard role to read() and write(). The abstract types can be declared so that existing functions work, just tin also be declared so that larger types can be represented in future implementations. It is presumed that whatever constraints limit the maximum range of size_t also limit portable I/O requests to the same range. This volume of IEEE Std 1003.one-2001 also limits the range further by requiring that the byte count exist express and then that a signed return value remains meaningful. Since the render type is as well a (signed) abstract type, the byte count can be defined by the implementation to be larger than an int can hold.
The standard developers considered adding atomicity requirements to a pipage or FIFO, merely recognized that due to the nature of pipes and FIFOs in that location could be no guarantee of atomicity of reads of {PIPE_BUF} or whatsoever other size that would be an assistance to applications portability.
This volume of IEEE Std 1003.1-2001 requires that no action exist taken for read() or write() when nbyte is nada. This is not intended to take precedence over detection of errors (such as invalid buffer pointers or file descriptors). This is consequent with the remainder of this volume of IEEE Std 1003.one-2001, but the phrasing here could be misread to require detection of the zero example before whatsoever other errors. A value of nil is to be considered a correct value, for which the semantics are a no-op.
I/O is intended to exist atomic to ordinary files and pipes and FIFOs. Atomic means that all the bytes from a unmarried operation that started out together end upwardly together, without interleaving from other I/O operations. Information technology is a known attribute of terminals that this is non honored, and terminals are explicitly (and implicitly permanently) excepted, making the behavior unspecified. The beliefs for other device types is likewise left unspecified, but the wording is intended to imply that future standards might choose to specify atomicity (or not).
There were recommendations to add format parameters to read() and write() in society to handle networked transfers amidst heterogeneous file system and base hardware types. Such a facility may be required for back up by the OSI presentation of layer services. However, it was adamant 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 time to come piece of work.
In 4.3 BSD, a read() or write() that is interrupted by a signal earlier transferring any data does non by default return an [EINTR] fault, but is restarted. In 4.2 BSD, iv.3 BSD, and the Eighth Edition, there is an additional function, select(), whose purpose is to intermission until specified action (information to read, space to write, then on) is detected on specified file descriptors. It is common in applications written for those systems for select() to be used before read() in situations (such as keyboard input) where interruption of I/O due to a signal is desired.
The issue of which files or file types are interruptible is considered an implementation design issue. This is ofttimes afflicted primarily by hardware and reliability bug.
There are no references to actions taken post-obit an "unrecoverable error". It is considered beyond the telescopic of this volume of IEEE Std 1003.1-2001 to depict what happens in the case of hardware errors.
Previous versions of IEEE Std 1003.ane-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 read() and write() return -ane and set up errno to [EINTR] when interrupted after some, but not all, of the data requested had been transferred. However, the U.Southward. Department of Commerce FIPS 151-i and FIPS 151-ii require the historical BSD beliefs, in which read() and write() render 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 fault on a seekable device and impossible on a non-seekable device. Nigh new implementations back up this behavior. The behavior required by IEEE Std 1003.1-2001 is to return the number of bytes transferred.
IEEE Std 1003.i-2001 does non specify when an implementation that buffers read()due south actually moves the data into the user-supplied buffer, so an implementation may cull to do this at the latest possible moment. Therefore, an interrupt arriving earlier may not cause read() to return a partial byte count, but rather to return -1 and set up errno to [EINTR].
Consideration was likewise given to combining the two previous options, and setting errno to [EINTR] while returning a brusque count. Still, not just is in that location no existing do that implements this, it is also contradictory to the idea that when errno is fix, the function responsible shall render -1.
Futurity DIRECTIONS
None.
See Too
fcntl(), ioctl(), lseek(), open up(), piping(), readv(), the Base Definitions volume of IEEE Std 1003.one-2001, Affiliate 11, Full general Concluding Interface, <stropts.h>, <sys/uio.h>, <unistd.h>
Modify HISTORY
First released in Event ane. Derived from Upshot 1 of the SVID.
Result v
The Clarification is updated for alignment with the POSIX Realtime Extension and the POSIX Threads Extension.
Large File Summit extensions are added.
The pread() office is added.
Issue 6
The DESCRIPTION and ERRORS sections are updated then that references to STREAMS are marked as role of the XSI STREAMS Pick Grouping.
The following new requirements on POSIX implementations derive from alignment with the Unmarried UNIX Specification:
The DESCRIPTION now states that if read() is interrupted by a betoken afterward it has successfully read some data, it returns the number of bytes read. In Issue 3, information technology was optional whether read() returned the number of bytes read, or whether it returned -1 with errno set up to [EINTR]. This is a FIPS requirement.
In the DESCRIPTION, text is added to bespeak that for regular files, no data transfer occurs by the start maximum established in the open file description associated with fildes. This change is to support large files.
The [EOVERFLOW] mandatory error condition is added.
The [ENXIO] optional error condition is added.
Text referring to sockets is added to the DESCRIPTION.
The post-obit changes were fabricated to align with the IEEE P1003.1a draft standard:
The effect of reading zero bytes is antiseptic.
The Clarification is updated for alignment with IEEE Std 1003.1j-2000 past specifying that read() results are unspecified for typed retentivity objects.
New RATIONALE is added to explain the atomicity requirements for input and output operations.
The post-obit error conditions are added for operations on sockets: [EAGAIN], [ECONNRESET], [ENOTCONN], and [ETIMEDOUT].
The [EIO] error is made optional.
The following error conditions are added for operations on sockets: [ENOBUFS] and [ENOMEM].
The readv() function is split out into a separate reference page.
IEEE Std 1003.i-2001/Cor 2-2004, item XSH/TC2/D6/108 is applied, updating the [EAGAIN] error in the ERRORS section from "the process would be delayed" to "the thread would be delayed".
IEEE Std 1003.i-2001/Cor two-2004, item XSH/TC2/D6/109 is practical, making an editorial correction in the RATIONALE section.
Terminate of informative text.
POSIX ® is a registered Trademark of The IEEE.
[ Master Alphabetize | XBD | XCU | XSH | XRAT ]
Source: https://pubs.opengroup.org/onlinepubs/009604599/functions/read.html
0 Response to "Reading to the End of a File in C"
Post a Comment