HP 3000 Manuals HP 3000 Manuals
RECV
C Interface
#include <sys/types.h>
#include <sys/socket.h>
recv(s, buf, len, flags)
int s;
char *buf;
int len, flags;
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>
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>
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:
[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
read, select, send, socket