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.
| Value | Meaning |
|---|---|
| Greater than zero | The time, in milliseconds, to wait. |
| Zero | Return immediately. |
| Less than zero | Wait indefinitely. |
Return value
Returns one of the following values.
| Return value | Description |
|---|---|
| Zero | No sockets were in the queried state before the timer expired. |
| Greater than zero | The number of elements in fdarray for which an revents member of the POLLFD structure is nonzero. |
| SOCKET_ERROR | An error occurred. Call the WSAGetLastError function to retrieve the extended error code. |
| Extended Error code | Meaning |
|---|---|
| The network subsystem has failed. | |
| An exception occurred while reading user input parameters. | |
| An invalid parameter was passed. This error is returned if the WSAPOLLFD structures pointed to by the fdarray parameter when requesting socket status. This error is also returned if none of the sockets specified in the fd member of any of the WSAPOLLFD structures pointed to by the fdarray parameter were valid. | |
| The function was unable to allocate sufficient memory. |
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:
| Flag | Description |
|---|---|
| POLLPRI | Priority data may be read without blocking. This flag is not supported by the Microsoft Winsock provider. |
| POLLRDBAND | Priority band (out-of-band) data may be read without blocking. |
| POLLRDNORM | Normal data may be read without blocking. |
| POLLWRNORM | Normal data may be written without blocking. |
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:
| Flag | Description |
|---|---|
| POLLERR | An error has occurred. |
| POLLHUP | A stream-oriented connection was either disconnected or aborted. |
| POLLNVAL | An invalid socket was used. |
| POLLPRI | Priority data may be read without blocking. This flag is not returned by the Microsoft Winsock provider. |
| POLLRDBAND | Priority band (out-of-band) data may be read without blocking. |
| POLLRDNORM | Normal data may be read without blocking. |
| POLLWRNORM | Normal data may be written without blocking. |
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
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 8.1, Windows Vista [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2008 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | winsock2.h (include Winsock2.h) |
| Library | Ws2_32.lib |
| DLL | Ws2_32.dll |