WSAPoll function (winsock2.h)

The WSAPoll function determines status of one or more sockets.

Syntax

int WSAAPI WSAPoll(
  [in, out] LPWSAPOLLFD fdArray,
  [in]      ULONG       fds,
  [in]      INT         timeout
);

Parameters

[in, out] fdArray

An array of one or more POLLFD structures specifying the set of sockets for which status is requested. The array must contain at least one structure with a valid socket. Upon return, this parameter receives the updated sockets with the revents status flags member set on each one that matches the status query criteria.

[in] fds

The number of WSAPOLLFD structures in fdarray. This is not necessarily the number of sockets for which status is requested.

[in] timeout

A value that specifies the wait behavior, based on the following values.

Return value

Returns one of the following values.

Remarks

The WSAPoll function is defined on Windows Vista and later.

The WSAPOLLFD structures. An application sets the appropriate flags in the events member of the WSAPOLLFD structure to specify the type of status requested for each corresponding socket. The WSAPoll function returns the status of a socket in the revents member of the WSAPOLLFD structure.

For each socket, a caller can request information on read or write status. Error conditions are always returned, so information on them need not be requested.

The WSAPOLLFD structure pointed to by the fdarray parameter. All sockets that do not meet these criteria and have no error condition will have the corresponding revents member set to 0.

A combination of the following flags can be set in the WSAPOLLFD structure for a given socket when requesting status for that socket:

The POLLIN flag is defined as the combination of the POLLRDNORM and POLLRDBAND flag values. The POLLOUT flag is defined as the same as the POLLWRNORM flag value.

The WSAPOLLFD structure must only contain a combination of the above flags that are supported by the Winsock provider. Any other values are considered errors and WSAPoll will return SOCKET_ERROR. A subsequent call to the WSAGetLastError function will retrieve the extended error code of WSAEINVAL. If the POLLPRI flag is set on a socket for the Microsoft Winsock provider, the WSAPoll function will fail.

When the WSAPOLLFD structures pointed to by the fdarray parameter to indicate socket status:

With regard to TCP and UDP sockets:

• WSAPOLLFD structure as normal data as POLLRDNORM.
• WSAPOLLFD structure, a subsequent recv operation is guaranteed to complete without blocking.
• WSAPOLLFD structure by POLLWRNORM.
• WSAPOLLFD structure by POLLRDNORM. A subsequent call to accept is guaranteed to complete without blocking.
• WSAPOLLFD structure by POLLRDBAND.
• WSAPOLLFD structure when a remote peer shuts down a send operation (a TCP FIN was received). A subsequent recv function request will return zero bytes.
• WSAPOLLFD structure when the remote peer initiates a graceful disconnect.
• WSAPOLLFD structure returned when a remote peer suddenly disconnects.
• WSAPOLLFD structure when the local socket is closed.

The number of elements (not sockets) in fdarray is indicated by nfds. Members of fdarray which have their fd member set to a negative value are ignored and their revents will be set to POLLNVAL upon return. This behavior is useful to an application which maintains a fixed fdarray allocation and will not compact the array to remove unused entries or to reallocate memory. It is not necessary to clear revents for any element prior to calling WSAPoll.

The timeout argument specifies how long the function is to wait before returning. A positive value contains the number of milliseconds to wait before returning. A zero value forces WSAPoll to return immediately, and a negative value indicates that WSAPoll should wait indefinitely.

Windows 8.1 and Windows Server 2012 R2: This function is supported for Windows Store apps on Windows 8.1, Windows Server 2012 R2, and later.

Requirements

See also

WSAGetLastError

WSAPOLLFD