recv

This function receives data from a socket.

At a Glance

Syntax

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

Parameters

s

[in] Descriptor that identifies a connected socket.

buf

[out] Buffer for the incoming data.

len

[in] Length of buf.

flags

[in] Specifies the way in which the call is made.

Return Values

Zero indicates that the connection has been gracefully closed. SOCKET_ERROR indicates failure. To get a specific error value, call WSAGetLastError.

Remarks

The recv function is used to read incoming data on connection-oriented sockets, or connectionless sockets. When using a connection-oriented protocol, the sockets must be connected before calling recv. When using a connectionless protocol, the sockets must be bound and connect must be called to associate the remote address before calling recv.

The local address of the socket must be known. For server applications, use an explicit bind function or an implicit accept function. Explicit binding is discouraged for client applications. For client applications the socket can become bound implicitly to a local address using connect or sendto.

For connection-oriented or connectionless sockets, this function restricts the addresses from which received messages are accepted. The function only returns messages from the remote address specified in the connection. Messages from other addresses are (silently) discarded.

For connection-oriented sockets (type SOCK_STREAM for example), calling recv will return as much information as is currently available—up to the size of the buffer supplied. The application can use the ioctlsocket or WSAIoctl SIOCATMARK command to determine whether any more out-of-band data remains to be read.

For connectionless sockets (type SOCK_DGRAM or other message-oriented sockets), data is extracted from the first enqueued datagram (message) from the destination address specified by the connect function.

If the datagram or message is larger than the buffer supplied, the buffer is filled with the first part of the datagram, and recv generates the error WSAEMSGSIZE. For unreliable protocols (for example, UDP) the excess data is lost; for reliable protocols, the data is retained by the service provider until it is successfully read by calling recv with a large enough buffer. For TCP/IP, an application cannot receive from any multicast address until after becoming a group member.

If no incoming data is available at the socket, the recv call blocks and waits for data to arrive. When the socket is nonblocking, a value of SOCKET_ERROR is returned with the error value set to WSAEWOULDBLOCK. The select function can be used to determine when more data arrives.

Any data that has already been received and buffered by the transport will be copied into the supplied user buffers. In the case of a blocking socket with no data currently having been received and buffered by the transport, the call will block until data is received. For protocols acting as byte-stream protocols, the stack tries to return as much data as possible, subject to the supplied buffer space and amount of received data available. However, receipt of a single byte is sufficient to unblock the caller. There is no guarantee that more than a single byte will be returned. For message-oriented protocols, a full message is required to unblock the caller.

If the socket is connection oriented and the remote side has shut down the connection gracefully, and all data has been received, a recv will complete immediately with zero bytes received. If the connection has been reset, a recv will fail with the error WSAECONNRESET.

The flags parameter can be used to influence the behavior of the function invocation beyond the options specified for the associated socket. The semantics of this function are determined by the socket options and the flags parameter. Windows CE supports the following flags parameter:

MSG_PEEK

Peek at the incoming data. The data is copied into the buffer but is not removed from the input queue. The function then returns the number of bytes currently pending to receive.

See Also

accept, bind, recvfrom, send, select, shutdown, socket, WSAStartup