HP-UX Reference (11i v3 07/02) - 2 System Calls (vol 5)

r
recv(2) recv(2)
the user as soon as it becomes available, and no data is discarded. See the AF_CCITT Only subsection
below for a list of the exceptions to this behavior for connections in the address family AF_CCITT.
recvmsg() performs the same action as recv(), but scatters the read data into the buffers specified in
the
msghdr structure (see X/Open Sockets Only below). This structure is defined in
<sys/socket.h>
and has the following form (HP-UX BSD Sockets Only
):
struct msghdr {
caddr_t msg_name; /* optional address */
int msg_namelen; /* size of address */
struct iovec *msg_iov; /* scatter array for data */
int msg_iovlen; /* # of elements in msg_iov */
caddr_t msg_accrights; /* access rights */
int msg_accrightslen; /* size of msg_accrights */
}
msg_name points to a sockaddr structure in which the address of the sending socket is to be stored, if
the socket is connectionless; msg_name may be a null pointer if no name is specified. msg_iov specifies the
locations of the character arrays for storing the incoming data. msg_accrights specifies a buffer to receive
any access rights sent along with the message. Access rights are limited to file descriptors of size int.If
access rights are not being transferred, set the msg_accrights field to NULL. Access rights are supported
only for AF_UNIX.
By default,
recv(), recvfrom() and recvmsg() are blocking system calls and do not complete until
there is data to read or the end of the socket data stream is reached (the remote side of a connection-based
socket has performed an orderly shutdown and there is no more data to read).
There are three ways to enable nonblocking mode:
• With the FIOSNBIO ioctl() request
• With the O_NONBLOCK fcntl() flag
• With the O_NDELAY fcntl() flag
Although the use of FIONBIO is not recommended, if nonblocking I/O is enabled using FIOSNBIO or the
equivalent
FIONBIO request (defined in <sys/ioctl.h>
and explained in ioctl(2), ioctl(5) and
socket(7)), the
recv() request completes in one of six ways:
• If there is enough data available to satisfy the entire request, recv() completes successfully, having
read all of the data, and returns the number of bytes read.
• If there is not enough data available to satisfy the entire request, recv() completes successfully,
having read as much data as possible, and returns the number of bytes it was able to read.
• If there is no data available,
recv() returns −1 and errno is set to [EWOULDBLOCK].
• If the remote side of a connection-based socket has performed an orderly shutdown and there is no
more data to read (the socket has reached the end of its data stream), recv() returns 0.
• If the remote side of a connection-based socket has reset the connection,
recv() returns −1 and sets
errno to [ECONNRESET].
• If an error occurs, recv() returns −1 and sets errno to indicate the error.
If nonblocking I/O is disabled using FIOSNBIO, recv() always executes completely (blocking as neces-
sary) and returns the number of bytes read.
If the O_NONBLOCK flag is set using fcntl() (defined in <sys/fcntl.h> and explained in fcntl(2)
and fcntl(5)), POSIX-style nonblocking I/O is enabled. In this case, the
recv() request completes in one
of six ways:
• If there is enough data available to satisfy the entire request, recv() completes successfully, having
read all the data, and returns the number of bytes read.
• If there is not enough data available to satisfy the entire request, recv() completes successfully,
having read as much data as possible, and returns the number of bytes it was able to read.
• If there is no data available, recv() completes, having read no data, and returns −1 and sets errno
to [EAGAIN].
• If the remote side of a connection-based socket has performed an orderly shutdown and there is no
more data to read (the socket has reached the end of its data stream), recv() returns 0.
336 Hewlett-Packard Company − 2 − HP-UX 11i Version 3: February 2007