read(2) CLIX read(2)
NAME
read - Reads from a file
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
int read(
int file_des ,
char *buffer ,
unsigned nbytes );
PARAMETERS
file_des Specifies a file descriptor identifying the object to be read.
This parameter is obtained from a call to the creat(), open(),
dup(), fcntl(), pipe(), accept(), or socket() function.
buffer Points to the buffer into which the data will be placed.
nbytes Specifies the number of bytes read from the file associated
with the file_des parameter.
DESCRIPTION
The read() function attempts to read nbytes of data from the file
associated with the file_des parameter into the buffer pointed to by the
buffer parameter.
On regular files and devices capable of seeking, the read() starts at a
position in the file given by the file pointer associated with the
file_des parameter. Upon return from the read() function, the file
pointer is incremented by the number of bytes actually read.
Devices that are incapable of seeking always read from the current
position. The value of a file pointer associated with such a file is
undefined.
Upon successful completion, read() will return the number of bytes
actually read and placed in the buffer. This number will never be 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 signal, 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.
A read() from a STREAMS (see the intro() function) file can operate in the
2/94 - Intergraph Corporation 1
read(2) CLIX read(2)
following modes:
byte-stream
The default is byte-stream mode. This mode can be changed using
the I_SRDOPT ioctl() request (see the streamio special file), and
can be tested with the I_GRDOPT ioctl() request. In byte-stream
mode, read() will retrieve data from the stream until it retrieves
nbyte bytes or until there is no more data to be retrieved. Byte-
stream mode ignores message boundaries.
message-nondiscard
The read() function retrieves data until it has read nbyte bytes or
until it reaches a message boundary. If read() does not retrieve
all the data in a message, the remaining data is replaced on the
stream and can be retrieved by the next read() or getmsg() call.
message-discard
This mode also cause read() to retrieve data until it has retrieved
nbyte bytes, or it reaches a message boundary. However, unread
data remaining in a message after the read() call returns are
discarded, and are not available for a subsequent read() or
getmsg() call.
When attempting to read from an empty pipe (or FIFO):
⊕ If no process has the pipe open for writing, read() returns 0 to
indicate end-of-file.
⊕ If some process has the pipe open for writing:
-- If O_NDELAY and O_NONBLOCK are clear (the default), read() blocks
until some data is written or the pipe is closed by all processes
that had opened the pipe for writing.
-- If O_NDELAY is set, read() returns a value of 0.
-- If O_NONBLOCK is set, read returns a value of -1 and set the global
variable errno to EAGAIN.
When attempting to read from a character special file that supports non-
blocking reads, such as a terminal, and no data is currently available:
⊕ If O_NDELAY and O_NONBLOCK are clear (the default), read() blocks until
data becomes available.
⊕ If O_NDELAY is set, read() returns a value of 0.
⊕ If O_NONBLOCK is set, read() returns -1 and sets the global variable
errno to EAGAIN if no data is available. The use of the O_NONBLOCK
flag has no effect if there is some data available.
2 Intergraph Corporation - 2/94
read(2) CLIX read(2)
When attempting to read a regular file with mandatory file/record locking
set, and a blocking (that is, owned by another process) write lock is on
the segment of the file to be read, one of the following will occur:
⊕ If O_NDELAY and O_NONBLOCK are clear, read() blocks the calling process
until the lock is released.
⊕ If O_NDELAY or O_NONBLOCK is set, read() returns -1 and sets the global
variable errno to EAGAIN.
When reading from a STREAMS file, zero-byte message handling is determined
by the current read mode setting. In byte-stream mode, read() accepts
data until it reads nbyte bytes, until there is no more data to read, or
until a zero-byte message block is encountered. The read() function then
returns the number of bytes read and places the zero-byte message back on
the stream to be retrieved by the next read() or getmsg(). In the two
other modes, a zero-byte message returns a value of 0 and the message is
removed from the stream. When a zero-byte message is read as the first
message on a stream, a value of -1 is returned regardless of the read
mode.
A read() from a STREAMS file can only process data messages. It cannot
process any type of protocol message and will fail if a protocol message
is encountered at the stream head.
EXAMPLES
char buf[BUFSIZ];
num_bytes = read(fd, buf, BUFSIZ);
if (num_bytes == -1)
perror("Read failed");
RETURN VALUES
Upon successful completion, the read() function returns the number of
bytes actually read and placed into buffers. Otherwise, a value of -1 is
returned and the global variable errno is set to identify the error, and
the content of the buffer pointed to by buffer is indeterminate.
ERRORS
The read() function fails if one or more of the following are true:
[EBADF]
The file_des parameter is not a valid file descriptor open for
reading.
[EINVAL]
Attempted to read from a stream linked to a multiplexor.
2/94 - Intergraph Corporation 3
read(2) CLIX read(2)
[EAGAIN]
Mandatory file/record locking was set, the file was marked for
non-blocking I/O, and there was a blocking record lock. This error
also occurs if the total amount of system memory available when
reading through raw I/O is temporarily insufficient, or if no
message was waiting to be read on a stream and a non-blocking I/O
flag was set.
[EFAULT]
The buffer parameter points to a location outside of the allocated
address space of the process.
[EDEADLK]
The read() function was going to sleep and caused a deadlock
situation to occur.
[EINTR]
A signal was caught during the read() function.
[EBADMSG]
The message waiting to be read on a stream is not a data message.
[ENOLCK]
The system record lock table was full, so the read() could not go
to sleep until the blocking record lock was removed.
[ENOLINK]
The fildes parameter is on a remote machine and the link to that
machine is no longer active.
[EWOULDBLOCK]
The descriptor references a socket marked as nonblocking and the
requested operation would block.
[ECONNRESET]
The descriptor references a socket where the connection is broken
and there is no more data to read.
A read() from a STREAMS file also fails if an error message is received at
the stream head. In this case, errno is set to the value returned in the
error message. If a hangup occurs on the stream being read, read() will
continue to operate normally until the stream head read queue is empty.
Thereafter, it will return 0.
RELATED INFORMATION
Functions: accept(2), creat(2), dup(2), fcntl(2), getmsg(2), ioctl(2),
intro(2), open(2), pipe(2), socket(2), socketpair(2), opendir(3),
readdir(3), seekdir(3)
Files: termio(7), streamio(7)
4 Intergraph Corporation - 2/94
read(2) CLIX read(2)
CLIX Programming Guide
2/94 - Intergraph Corporation 5