ManPage: read(2v)

read() attempts to read nbyte bytes of data from the object referenced by the descriptor fd into the buffer pointed to by buf. readv() performs the same action as read(), but scatters the input data into the iovcnt buffers specified by the members of the iov array: iov[0],iov[1], ..., iov[iovcnt-1].

If nbyte is zero, read() takes no action and returns 0. readv(), however, returns -1 and sets the global variable errno (see ERRORS below).

For readv(), the iovec structure is defined as

struct iovec {
caddr_t iov_base;
int iov_len; };

Each

iovec

entry specifies the base address and length of an area

in memory where data should be placed.

readv()

will always fill an area completely before proceeding to the next.

On objects capable of seeking, the

read()

starts at a position given by the pointer associated with

(see

lseek(2V)).

Upon return from

read(),

the pointer is incremented by the number of bytes actually read.

Objects that are not capable of seeking always read from the current

position. The value of the pointer associated with such an object is

undefined.

Upon successful completion,

read()

and

readv()

return the number of bytes actually read and placed in the buffer.

The system guarantees to read the number of bytes requested if

the descriptor references a normal file which has that many bytes left

before the

EOF

(end of file),

but in no other case.

If the process calling

read()

readv()

receives a signal before any data are read, the system call is restarted

unless the process explicitly set the signal to interrupt the call using

sigvec()

sigaction()

(see the discussions of

SV_INTERRUPT

sigvec(2)

and

SA_INTERRUPT

sigaction(3V)).

read()

readv()

is interrupted by a signal after successfully reading some data,

it returns the number of bytes read.

nbyte

is not zero and

read()

returns 0, then

EOF

has been reached.

readv()

returns 0, then

EOF

has been reached.

read()

readv()

from a

STREAMS

file

(see

intro(2))

can operate in three different modes: (byte-stream) mode,

(message-nondiscard) mode, and (message-discard) mode.

The default is byte-stream mode.

This can be changed using the

I_SRDOPT

ioctl(2)

request (see

streamio(4)),

and can be tested with the

I_GRDOPT

ioctl()

request.

In byte-stream mode,

read()

and

readv()

will 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.

STREAMS

message-nondiscard mode,

read()

and

readv()

will retrieve data until as many bytes as were requested are transferred,

or until a message boundary is reached. If the

read()

readv()

does not retrieve all the data in a message,

the remaining data are left on the

stream,

and can be retrieved by the next

read(),

readv(),

getmsg(2)

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

read()

readv()

returns are discarded, and are not available for a

subsequent

read(),

readv(),

getmsg().

When attempting to read from a descriptor associated with an empty pipe,

socket,

FIFO,

stream:

If the object the descriptor is associated with is marked for

4.2BSD-style

non-blocking I/O (with the

FIONBIO

ioctl()

request or a call to

fcntl(2V)

using the

FNDELAY

flag from

<sys/file.h>

or the

O_NDELAY

flag from

<fcntl.h>

in the 4.2BSD

environment), the read will return -1 and

errno

will be set to

EWOULDBLOCK.

If the descriptor is marked for System V-style non-blocking I/O (using

fcntl()

with the

FNBIO

flag from

<sys/file.h>

or the

O_NDELAY

flag from

<fcntl.h>

in the System V environment), and does not refer to a

stream,

the read will return 0. Note: this

is indistinguishable from

EOF.

If the descriptor is marked for POSIX-style non-blocking I/O

(using

fcntl()

with the

O_NONBLOCK

flag from

<fcntl.h>)

and refers to a

stream,

the read will return -1 and

errno

will be set to

EAGAIN.

If neither the descriptor nor the object it refers to are marked for

non-blocking I/O, the read will block until data is available to

be read or the object has been lqdisconnectedrq. A pipe or

FIFO

is lqdisconnectedrq when no process has the

object open for writing; a socket that was connected is

lqdisconnectedrq when the connection is broken; a stream is

lqdisconnectedrq when a hangup condition occurs

(for instance, when carrier

drops on a terminal).

If the descriptor or the object is marked for non-blocking I/O,

and less data are available than are requested by the

read()

readv(),

only the data that are available are returned, and the count indicates how

many bytes of data were actually read.

When reading from a

STREAMS

file, handling of zero-byte messages is

determined by the current read mode setting.

In byte-stream mode,

read()

and

readv()

accept data until as many bytes as were requested are transferred,

or until there is no more data to read, or until a zero-byte message

block is encountered.

read()

and

readv()

then return the number of bytes read, and places the zero-byte

message back on the

stream

to be retrieved by the next

read(),

readv(),

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 0 is returned regardless of the read mode.

read()

readv()

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

streamhead.

Upon successful completion,

read()

and

readv()

mark for update the

st_atime

field of the file.

EAGAIN: The descriptor referred to a stream, was marked for System V-style non-blocking I/O, and no data were ready to be read.
EBADF: d is not a valid file descriptor open for reading.
EBADMSG: The message waiting to be read on a stream is not a data message.
EFAULT: buf points outside the allocated address space.
EINTR: The process performing a read from a slow device received a signal before any data arrived, and the signal was set to interrupt the system call.
EINVAL: The stream is linked below a multiplexor. The pointer associated with fd was negative.
EIO: An I/O error occurred while reading from or writing to the file system. The calling process is in a background process group and is attempting to read from its controlling terminal and the process is ignoring or blocking SIGTTIN. The calling process is in a background process group and is attempting to read from its controlling terminal and the process is orphaned.
EISDIR: fd refers to a directory which is on a file system mounted using the NFS.
EWOULDBLOCK: The file was marked for 4.2BSD-style non-blocking I/O, and no data were ready to be read.

In addition to the above, readv() may set errno to:

EFAULT: Part of iov points outside the process's allocated address space.
EINVAL: iovcnt was less than or equal to 0, or greater than 16. One of the iov_len values in the iov array was negative. The sum of the iov_len values in the iov array overflowed a 32-bit integer.

A read() or readv() from a STREAMS file will also fail 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.