recvfrom
A version of this page is also available for
4/8/2010
This function receives a datagram and stores the source address.
Syntax
int recvfrom(
SOCKET s,
char FAR* buf,
int len,
int flags,
struct sockaddr FAR* from,
int FAR* fromlen
);
Parameters
- s
[in] Descriptor identifying a bound socket.
- buf
[out] Buffer for the incoming data.
- len
[in] Length of the buf parameter.
- flags
[in] Indicator specifying the way in which the call is made.
- from
[out] Optional pointer to a buffer that will hold the source address on return.
- fromlen
[in, out] Optional pointer to the size of the from buffer.
Return Value
If no error occurs, this function returns the number of bytes received. If the connection has been gracefully closed, the return value is zero. If an error occurs, a value of SOCKET_ERROR is returned, and a specific error code can be retrieved by calling WSAGetLastError.
The following table shows a list of possible error codes.
| Error code | Description |
|---|---|
WSANOTINITIALISED |
A successful WSAStartup call must occur before using this function. |
WSAENETDOWN |
The network subsystem has failed. |
WSAEFAULT |
The buf or from parameters are not part of the user address space, or the fromlen parameter is too small to accommodate the peer address. |
WSAEINTR |
The socket was closed. |
WSAEINPROGRESS |
A blocking Winsock call is in progress, or the service provider is still processing a callback function. |
WSAEINVAL |
The socket has not been bound with bind (Windows Sockets), an unknown flag was specified, MSG_OOB was specified for a socket with SO_OOBINLINE enabled, or (for byte stream-style sockets only) len was zero or negative. |
WSAEISCONN |
The socket is connected. The recvfrom function is not permitted with a connected socket, whether the socket is connection-oriented or connectionless. |
WSAENETRESET |
The connection has been broken due to the keep-alive activity detecting a failure while the operation was in progress. |
WSAENOTSOCK |
The descriptor is not a socket. WSAEOPNOTSUPP MSG_OOB was specified, but the socket is not stream style such as type SOCK_STREAM, out of band (OOB) data is not supported in the communication domain associated with this socket, or the socket is unidirectional and supports only send operations. |
WSAESHUTDOWN |
The socket has been shut down. It is not possible to call recvfrom on a socket after shutdown has been invoked with how set to SD_RECEIVE or SD_BOTH. |
WSAEWOULDBLOCK |
The socket is marked as nonblocking and the recvfrom operation would block. |
WSAEMSGSIZE |
The message was too large to fit into the specified buffer and was truncated. |
WSAETIMEDOUT |
The connection has been dropped because of a network failure or because the system on the other end went down without notice. |
WSAECONNRESET |
The virtual circuit was reset by the remote side executing a hard or abortive close. The application should close the socket because it is no longer usable. |
Remarks
This function reads incoming data on both connected and unconnected sockets and captures the address from which the data was sent. The local address of the socket must be known. For server applications, this is usually done explicitly through bind (Windows Sockets). Explicit binding is discouraged for client applications. For client applications using this function, the socket can become bound implicitly to a local address through sendto, or WSASendTo.
For stream-oriented sockets such as those of type SOCK_STREAM, a call to recvfrom returns as much information as is currently available — up to the size of the buffer supplied. If the socket has been configured for inline reception of out of band (OOB) data (socket option SO_OOBINLINE) and OOB data is yet unread, only OOB data will be returned. The application can use the ioctlsocket or WSAIoctl function SIOCATMARK command to determine whether any more OOB data remains to be read. The from and fromlen parameters are ignored for connection-oriented sockets.
For message-oriented sockets, data is extracted from the first enqueued message, up to the size of the buffer supplied. If the datagram or message is larger than the buffer supplied, the buffer is filled with the first part of the datagram and recvfrom generates the error WSAEMSGSIZE. For unreliable protocols (for example, UDP) the excess data is lost.
If the from parameter is nonzero and the socket is not connection-oriented, (type SOCK_DGRAM, for example), the network address of the peer that sent the data is copied to the corresponding sockaddr structure. The value pointed to by fromlen is initialized to the size of this structure and is modified, on return, to indicate the actual size of the address stored in the sockaddr structure.
If no incoming data is available at the socket, the recvfrom function blocks and waits for data to arrive according to the blocking rules defined for WSARecv with the MSG_PARTIAL flag not set unless the socket is nonblocking. In this case, a value of SOCKET_ERROR is returned with the error code set to WSAEWOULDBLOCK. The select or WSAEventSelect function can be used to determine when more data arrives.
If the socket is connection-oriented and the remote side has shut down the connection gracefully, the call to recvfrom will complete immediately with zero bytes received. If the connection has been reset, recvfrom 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 the recvfrom function are determined by the socket options and the flags parameter. The following table shows the values can be used to construct the flags parameter. The bitwise OR operator is applied to these values.
| Value | Description |
|---|---|
MSG_PEEK |
Peeks at the incoming data. The data is copied into the buffer but is not removed from the input queue, and the function returns the number of bytes currently pending to receive. |
MSG_OOB |
Processes OOB data. (See section DECnet Out-Of-band data for a discussion of this topic.) |
Requirements
| Header | winsock2.h |
| Library | Ws2.lib |
| Windows Embedded CE | Windows CE 1.0 and later |
| Windows Mobile | Windows Mobile Version 5.0 and later |
See Also
Reference
bind (Windows Sockets)
ioctlsocket
recv
select
send
sendto
shutdown
socket (Windows Sockets)
WSAEventSelect
WSAGetLastError
WSAIoctl
WSARecv
WSASendTo
WSAStartup