RECV(2) — Series 300 and 800 Only

NAME

recv, recvfrom − receive a message from a socket

SYNOPSIS

#include <sys/types.h>
#include <sys/socket.h>

cc = recv(s, buf, len, flags)
int cc, s;
char *buf;
int len, flags;

cc = recvfrom(s, buf, len, flags, from, fromlen)
int cc, s;
char *buf;
int len, flags;
struct sockaddr *from;
int *fromlen;

DESCRIPTION

Recv and recvfrom are used to receive messages from a socket.

S is a socket descriptor from which the messages will be received. Buf is a pointer to the buffer into which the messages are placed. Len is the maximum number of bytes that will fit into the buffer referenced by buf.

If the socket uses connection-based communications, such as a SOCK_STREAM socket, these calls may only be used after the connection has been established (see connect(2)). For connectionless sockets, such as SOCK_DGRAM, these calls may be used whether a connection has been specified or not.

Recvfrom operates just like recv does, except that it is able to return the address of the socket from which the message was sent. For connected sockets, recvfrom simply returns the same address as does getpeername(2). If from is non-zero, the source address of the message is placed into the socket address structure pointed to by from. Fromlen 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 will be returned.

The length of the message is returned in cc.

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 will be 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 messages are available at the socket, the receive call waits for a message to arrive, unless the socket is nonblocking (see socket(7)) in which case a cc of −1 is returned with the external variable errno set to EWOULDBLOCK.

The fcntl flag O_NDELAY is also supported. In this case, a recv with no data available will return with cc equal to zero. See fcntl(2) and socket(7) for more information.

The select(2) call may be used to determine when more data arrives by selecting the socket for reading.

The flags parameter can be set to MSG_PEEK, MSG_OOB or zero. If it is set to MSG_PEEK, any data returned to the user still is treated as if it had not been read. The next recv will re-read the same data. The MSG_OOB flag is used to alert the other process with an urgent message, using a logically independent transmission channel associated with a pair of connected stream sockets. Refer to "SEE ALSO" below for details. For stream-based TCP SOCK_STREAM sockets, both the MSG_PEEK and MSG_OOB flags can be set at the same time. The MSG_OOB flag value is supported for stream-based TCP SOCK_STREAM sockets only.

A read(2) call made to a socket will behave in exactly the same way as a recv with flags set to zero.

RETURN VALUE

If the call is successful, it returns the number of bytes received. If the call fails, −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.

DIAGNOSTICS

The call to recv or recvfrom will fail if:

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

[EINTR] The receive was interrupted by delivery of a signal before any data was available for the receive.

[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 active connection.

[ENOTCONN] Receive on a SOCK_STREAM socket that is not yet connected.

[EINVAL] Len is bad or no data available on receive of out of band data.

[EOPNOTSUPP] A recv/recvfrom was attempted on a SOCK_DGRAM socket that has not been bound or connected. A bind(2) or connect(2) should be done before the recv/recvfrom. Or, the MSG_OOB flag was set for a UDP SOCK_DGRAM message-based socket. The MSG_OOB flag is only supported for stream-based SOCK_STREAM sockets.

DEPENDENCIES

Implemented on the Series 300 and 800 only.

The MSG_OOB flag value is supported for stream-based TCP SOCK_STREAM sockets only.

AUTHOR

UCB (University of California at Berkeley)

Museum

Related Articles