Export (0) Print
Expand All
Expand Minimize

WSAPoll function

The WSAPoll function determines status of one or more sockets.

Syntax


int WSAAPI WSAPoll(
  _Inout_  WSAPOLLFD fdarray[],
  _In_     ULONG nfds,
  _In_     INT timeout
);

Parameters

fdarray [in, out]

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.

nfds [in]

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

timeout [in]

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

Return valueMeaning
Greater than zeroThe time, in milliseconds, to wait.
ZeroReturn immediately.
Less than zeroWait indefinitely.

 

Return value

Returns one of the following values.

ValueDescription
ZeroNo sockets were in the queried state before the timer expired.
Greater than zeroThe number of elements in fdarray for which an revents member of the POLLFD structure is nonzero.
SOCKET_ERRORAn error occurred. Call the WSAGetLastError function to retrieve the extended error code.

 

Extended Error codeMeaning
WSAENETDOWN

The network subsystem has failed.

WSAEFAULT

An exception occurred while reading user input parameters.

WSAEINVAL

An invalid parameter was passed. This error is returned if the fdarray parameter contains a NULL pointer. This error is also returned if invalid flags were specified in the events member of any of 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.

WSAENOBUFS

The function was unable to allocate sufficient memory.

 

Remarks

The WSAPoll function is defined on Windows Vista and later.

The WSAPoll function is used to determine the status of one or more sockets. The set of sockets for which status is requested is specified in fdarray parameter, which is an array of 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 fdarray parameter must contain at least one valid non-negative socket. Upon return, all of the supplied sockets that either satisfy the requested status conditions or have an error condition will have the appropriate flags set on the revents member of their corresponding 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 events member of the WSAPOLLFD structure for a given socket when requesting status for that socket:

FlagDescription
POLLPRIPriority data may be read without blocking. This flag is not supported by the Microsoft Winsock provider.
POLLRDBANDPriority band (out-of-band) data may be read without blocking.
POLLRDNORMNormal data may be read without blocking.
POLLWRNORMNormal 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 events member of 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 WSAPoll function returns a positive value, a combination of the following flags are returned in the revents member of the WSAPOLLFD structures pointed to by the fdarray parameter to indicate socket status:

FlagDescription
POLLERRAn error has occurred.
POLLHUPA stream-oriented connection was either disconnected or aborted.
POLLNVALAn invalid socket was used.
POLLPRIPriority data may be read without blocking. This flag is not returned by the Microsoft Winsock provider.
POLLRDBANDPriority band (out-of-band) data may be read without blocking.
POLLRDNORMNormal data may be read without blocking.
POLLWRNORMNormal data may be written without blocking.

 

With regard to TCP and UDP sockets:

  • All regular TCP data and all UDP data is considered normal. So if SO_OOBINLINE has been enabled for a socket, out-of-band data will be indicated in the returned revents member of WSAPOLLFD structure as normal data as POLLRDNORM.
  • When normal data is indicated in the returned revents member of WSAPOLLFD structure, a subsequent recv operation is guaranteed to complete without blocking.
  • Pending connect requests are indicated in the returned revents member of WSAPOLLFD structure by POLLWRNORM.
  • Pending connections on a listening socket are indicated in the returned revents member of WSAPOLLFD structure by POLLRDNORM. A subsequent call to accept is guaranteed to complete without blocking.
  • Any out-of-band data is considered priority band for TCP, and is indicated in the returned revents member of WSAPOLLFD structure by POLLRDBAND.
  • POLLRDNORM is indicated in the returned revents member of 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.
  • POLLHUP is indicated in the returned revents member of WSAPOLLFD structure when the remote peer initiates a graceful disconnect.
  • The POLLHUP and POLLERR are indicated in the returned revents member of WSAPOLLFD structure returned when a remote peer suddenly disconnects.
  • POLLERR is indicated in the returned revents member of 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 cleared 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.

Note  When issuing a blocking Winsock call such as WSAPoll with the timeout parameter set to a negative number, Winsock may need to wait for a network event before the call can complete. Winsock performs an alertable wait in this situation, which can be interrupted by an asynchronous procedure call (APC) scheduled on the same thread. Issuing another blocking Winsock call inside an APC that interrupted an ongoing blocking Winsock call on the same thread will lead to undefined behavior, and must never be attempted by Winsock clients.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Mswsock.h (include Winsock2.h)

Library

Ws2_32.lib

DLL

Ws2_32.dll

See also

WSAGetLastError
WSAPOLLFD

 

 

Community Additions

ADD
Show:
© 2014 Microsoft