|
|
|
C Interface
#include <sys/types.h>
#include <sys/socket.h>
int recv (s, buf, len, flags)
int s;
char *buf;
int len, flags;
int recvmsg (s, msg, flags)
int s;
struct msghdr msg[];
int flags;
AF_UNIX only:
#include <sys/types.h>
#include <sys/socket.h>
#include <sys/un.h>
int recvfrom (s, buf, len, flags, from, fromlen)
int s;
char *buf;
int len, flags;
struct sockaddr_un *from;
int *fromlen;
AF_INET only:
#include <sys/types.h>
#include <sys/socket.h>
#include <netinet/in.h>
int recvfrom (s, buf, len, flags, from, fromlen)
int s;
char *buf;
int len, flags;
struct sockaddr_in *from;
int *fromlen;
Description
The recv, recvfrom, and recvmsg calls are used to receive
messages from a socket.
The argument s is a socket descriptor from which the message
is received. The buf parameter is a pointer to the buffer into
which the messages are placed. The len parameter is the
maximum number of bytes that will fit into the buffer referenced by
buf.
If the socket uses connection-based communications (for example, a
SOCK_STREAM socket), then these calls can be used only after the
connection has been established. (Refer to
connect) For connection-less sockets (for
example, a SOCK_DGRAM socket), these calls can be used whether a
connection has been established or not.
The recvfrom call operates the same as the recv call does,
except that it is able to return the address of the socket from which the
message was sent. If from is non-zero, the source address of
the message is placed into the socket address structure pointed to by
from. The fromlen parameter is a value-result
parameter, initialized to the size of the structure associated with
from, and modified on return to indicate the actual size of
the address stored there. If the memory pointed to by from is
not large enough to contain the entire address, only the first
fromlen bytes of the address are returned.
The length of the message is the functional return.
For message-based sockets like SOCK_DGRAM, the entire message must be
read in one operation. If a message is too long to fit in the supplied buffer,
the excess bytes are discarded. For stream-based sockets like
SOCK_STREAM, there is no concept of message boundaries. In this case,
data is returned to the user as soon as it becomes available, and no data is
discarded.
If no data is available to be received, recv waits for a message to
arrive unless non-blocking mode is enabled. There are two ways to enable
non-blocking mode: with the O_NONBLOCK fcntl flag, and with
the O_NDELAY fcntl flag.
If O_NONBLOCK is set using sfcntl (defined in
<fcntl.h.sys> and explained in the fcntl section),
POSIX-style non-blocking I/O is enabled. In this case, the recv
request completes in one of three 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 that it was able to read.
- If there is no data available, recv completes successfully,
having read no data, and returns a -1 with errno set to
EAGAIN.
If O_NDELAY is set using sfcntl (defined in
<fcntl.h.sys> and explained in the fcntl section),
non-blocking I/O is enabled. In this case, the recv request completes
in one of three 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 that it was able to read.
- If there is no data available, recv completes successfully,
having read no data, and returns a 0.
If O_NONBLOCK or O_NDELAY is cleared using sfcntl,
the corresponding style of non-blocking I/O, if previously enabled, is
disabled. In this case, recv always executes completely (blocking as
necessary) and returns the number of bytes read.
To summarize, both behave the same if there is enough data available to
satisfy the entire request or even part of the request. They differ only in
the third case, where there is no data available.
The select call can be used to determine when more data arrives by
selecting the socket for reading.
The flags parameter can be set to MSG_PEEK or zero.
If it is set to MSG_PEEK, any data returned to the user is treated as
if it had not been read. The next recv rereads the same data. The
value is as follows:
#define MSG_PEEK 0x2 /* peek at incoming message */
A read call behaves the same way as a recv call with
flags set to zero.
The recv|msg call uses a msghdr structure to minimize
the number of directly supplied parameters. This structure has the following
form, as defined in <sys/socket.h>:
struct msghdr {
caddr_t msg_name; /* optional address */
int msg_namelen; /* size of address */
struct iov *msg_iov; /* scatter/gather array */
int msg_iovlen; /* # elements in msg_iov */
caddr_t msg_accrights; /* access rights sent/received */
int msg_accrightslen;
};
Here, msg_name and msg_namelen specify the
destination address if the socket is unconnected, and msg_name
can be given as a null pointer if no names are desired or required. The
msg_iov and msg_iovlen describe the scatter
gather locations, as described in read. Access rights to be sent with
the message are specified in msg_accrights, which has
msg_accrightslen.
Return Value
If the call is successful, it returns the number of bytes received. If the
call fails, a -1 is returned, and an error code is stored in
errno. A zero is returned if the socket is blocking and the
transport connection to the remote node fails.
Errors
The following errors are returned by recv, recvfrom, or
recvmsg:
| Error Code |
Description |
| [EBADF] |
The argument s is an invalid descriptor. |
| [ENOTSOCK] |
The argument s is not a socket. |
| [EWOULDBLOCK] |
The socket is marked non-blocking, and the receive operation would
block. |
| [EFAULT] |
The buf, from, or fromlen parameters are
not valid pointers. |
| [ETIMEDOUT] |
The connection timed out during connection establishment, or due to a
transmission timeout on an active connection. |
| [ENOTCONN] |
Receive on a SOCK_STREAM socket that is not yet
connected. |
| [EINVAL] |
The len parameter is bad or there is no data available
on a receive of out-of-band data. |
| [EINTR] |
The call was interrupted by a signal before a valid connection
arrived. |
| [EOPNOTSUPP] |
A receive was attempted on a SOCK_DGRAM socket that has not
been bound. A bind should be done before the
receive. |
| [ENOBUFS] |
Insufficient buffer memory is available. |
MPE/iX Specific
For AF_UNIX, recvfrom() is supported; however, the
from and fromlen parameters are ignored (that
is, it works just like recv()).
The recv call can only be done on SOCK_STREAM sockets.
The recvfrom call can only be done on SOCK_DGRAM sockets.
The MSG_OOB flag, used for processing out-of-band data, is not
supported on MPE/iX.
Author
UCB (University of California at Berkeley)
See Also
connect,
read,
select,
send,
sfcntl,
socket
|
