This chapter is from the book
This chapter is from the book
This chapter is from the book
3.7 read Function
Data is read from an open file with the read function.
#include <unistd.h>
ssize_t read(int filedes,
void *buff, size_t nbytes);
Returns: number of bytes read, 0 if end of file, –1 on error
If the read is successful, the number of bytes read is returned. If the end of file is encountered, 0 is returned.
There are several cases in which the number of bytes actually read is less than the amount requested:
-
When reading from a regular file, if the end of file is reached before the requested number of bytes has been read. For example, if there are 30 bytes remaining until the end of file and we try to read 100 bytes, read returns 30. The next time we call read it will return 0 (end of file).
-
When reading from a terminal device, normally up to one line is read at a time (we'll see how to change this in Chapter 11).
-
When reading from a network, buffering within the network may cause less than the requested amount to be returned.
-
Some record-oriented devices, such as a magnetic tape, return up to a single record at a time.
The read operation starts at the file's current offset. Before a successful return, the offset is incremented by the number of bytes actually read.
POSIX.1 changed the prototype for this function in several ways. The classic definition is
int read(int filedes, char *buff, unsigned nbytes);
First, the second argument was changed from a char * to a void * to be consistent with ANSI C: the type void * is used for generic pointers. Next, the return value must be a signed integer (ssize_t) to return either a positive byte count, 0 (for end of file), or -1 (for an error). Finally, the third argument historically has been an unsigned integer, to allow a 16-bit implementation to read or write up to 65534 bytes at a time. With the 1990 POSIX.1 standard the new primitive system data type ssize_t was introduced to provide the signed return value, and the unsigned size_t was used for the third argument. (Recall the SSIZE_MAX constant from Figure 2.7.)
){kind=link}