recvfrom()

Description

Receive a datagram and store the source address.

#include <winsock.h>

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

s

A descriptor identifying a bound socket.
buf
A buffer for the incoming data.
len
The length of buf.
flags
Specifies the way in which the call is made.
from
An optional pointer to a buffer which will hold the source address upon return.
fromlen
An optional pointer to the size of the from buffer.

Remarks

This function is used to read incoming data on a (possibly connected) socket and capture the address from which the data was sent.

For sockets of type SOCK_STREAM, as much information as is currently available up to the size of the buffer supplied is returned. If the socket has been configured for in-line reception of out-of-band data (socket option SO_OOBINLINE) and out-of-band data is unread, only out-of-band data will be returned. The application may use the ioctlsocket() SIOCATMARK to determine whether any more out-of-band data remains to be read. The from and fromlen parameters are ignored for SOCK_STREAM sockets.

For datagram sockets, data is extracted from the first enqueued datagram, up to the size of the size of the buffer supplied. If the datagram is larger than the buffer supplied, the buffer is filled with the first part of the message, the excess data is lost, and recvfrom() returns the error code WSAEMSGSIZE. If from is non-zero, and the socket is of type SOCK_DGRAM, the network address of the peer which sent the data is copied to the corresponding struct sockaddr. 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 there.

If no incoming data is available at the socket, the recvfrom() call waits for data to arrive unless the socket is non-blocking. In this case a value of SOCKET_ERROR is returned with the error code set to WSAEWOULDBLOCK. The select() or WSAAsyncSelect() calls may be used to determine when more data arrives. If the socket is of type SOCK_STREAM and the remote side has shut down the connection gracefully, a recvfrom() will complete immediately with 0 bytes received. If the connection has been abortively disconnected, a recvfrom() will fail with the error WSAECONNRESET.

Flags may be used to influence the behavior of the function invocation beyond the options specified for the associated socket. That is, the semantics of this function are determined by the socket options and the flags parameter. The latter is constructed by or-ing any of the following values:

MSG_PEEK

Peek at the incoming data. The data is copied into the buffer but is not removed from the input queue.
MSG_OOB
Process out-of-band data (See Out of Band Data for a discussion of this topic.)

Return Value

If no error occurs, recvfrom() returns the number of bytes received. If the connection has been closed, it returns 0. Otherwise, a value of SOCKET_ERROR is returned, and a specific error code may be retrieved by calling WSAGetLastError().

Error Codes

WSANOTINITIALISED

A successful WSAStartup() must occur before using this API.
WSAENETDOWN
The Windows Sockets implementation has detected that the network subsystem has failed.
WSAEFAULT
The fromlen argument was invalid: the from buffer was too small to accommodate the peer address.
WSAEINTR
The (blocking) call was canceled via WSACancelBlockingCall()
WSAEINPROGRESS
A blocking Windows Sockets operation is in progress.
WSAEINVAL
The socket has not been bound with bind().
WSAENOTCONN
The socket is not connected (SOCK_STREAM only).
WSAENOTSOCK
The descriptor is not a socket.
WSAEOPNOTSUPP
MSG_OOB was specified, but the socket is not of type SOCK_STREAM.
WSAESHUTDOWN
The socket has been shutdown; it is not possible to recvfrom() on a socket after shutdown() has been invoked with how set to 0 or 2.
WSAEWOULDBLOCK
The socket is marked as non-blocking and the recvfrom() operation would block.
WSAEMSGSIZE
The datagram was too large to fit into the specified buffer and was truncated.
WSAECONNABORTED
The virtual circuit was aborted due to timeout or other failure.
WSCONNRESET
The virtual circuit was reset by the remote side.

See Also

recv(), send(), socket(), WSAAsyncSelect()

---

[Back: recv()]
[Next: select()]