>>-read--fd--variable--length----------------------------------><
Parameters
- fd
- The file descriptor (a number) for the file to be read.
- variable
- The name of the buffer into which the data is to be read.
- length
- The maximum number of characters to read. After the read completes,
the length of variable is the number of
bytes read. This value is also returned in RETVAL.
Usage notes
- Length:
- The value of length is not checked against
any system limit.
- Access time:
- A successful read updates the access time of the file read.
- Origin of bytes read:
- If the file specified by fd is a regular
file, or any other type of file where a seek operation is possible,
bytes are read from the file offset associated with the file descriptor.
A successful read increments the file offset by the number of bytes
read.
For files where no seek operation is possible, there is no
file offset associated with the file descriptor. Reading begins at
the current position in the file.
- Number of bytes read:
- When a read request completes, the RETVAL field shows the number
of bytes actually read—a number less than or equal to the number specified
as length. The following are some reasons
why the number of bytes read might be less than the number of bytes
requested:
- Fewer than the requested number of bytes remained in the file;
the end of file was reached before length bytes
were read.
- The service was interrupted by a signal after some but not all
of the requested bytes were read. (If no bytes were read, the return
value is set to -1 and an error is reported.)
- The file is a pipe, FIFO, or special file and fewer bytes than length specified
were available for reading.
There are several reasons why a read request might complete
successfully with no bytes read (that is, with RETVAL set to
0).
For example, zero bytes are read in these cases:
- The call specified a length of zero.
- The starting position for the read was at or beyond the end of
the file.
- The file being read is a FIFO file or a pipe, and no process has
the pipe open for writing.
- The file being read is a slave pseudoterminal and a zero-length
canonical file was written to the master.
- Nonblocking:
- If a process has a pipe open for reading with nonblocking specified,
a request to read from the file ends with a return value of -1 a
return code of 0, and ERRNO of EAGAIN.
But if nonblocking was not specified, the read request is blocked
(does not return) until some data is written or the pipe is closed
by all other processes that have the pipe open for writing.
Both
master and slave pseudoterminals operate this way, too, except that
how they act depends on how they were opened. If the master or the
slave is opened blocking, the reads are blocked if there is no data.
If it is opened nonblocking, EAGAIN is returned if there is no data.
- SIGTTOU processing:
- The read service causes signal SIGTTIN to be sent under the following
conditions:
- The process is attempting to read from its controlling terminal,
and
- The process is running in a background process group, and
- The SIGTTIN signal is not blocked or ignored, and
- The process group of the process is not orphaned.
If these conditions are met, SIGTTIN is sent. If SIGTTIN
has a handler, the handler gets control and the read ends with the
return code set to EINTRO. If SIGTTIN is set to default, the process
stops in the read and continues when the process is moved to the foreground.
Example
In the following example, assume
that
fd was assigned a value earlier in
the exec. This reads 1000 characters from the file
fd into
the buffer
buf:
"read (fd) buf 1000"