select

Article
11/18/2015

A version of this page is also available for

4/8/2010

This function determines the status of one or more sockets, waiting if necessary, to perform synchronous I/O.

Syntax

int select(
  int nfds,
  fd_set FAR* readfds,
  fd_set FAR* writefds,
  fd_set FAR* exceptfds,
  const struct timeval FAR* timeout
);

Parameters

nfds
[in] Ignored. The nfds parameter is included only for compatibility with Berkeley sockets.

readfds
[in, out] Optional pointer to a set of sockets to be checked for readability.

writefds
[in, out] Optional pointer to a set of sockets to be checked for writability.

exceptfds
[in, out] Optional pointer to a set of sockets to be checked for errors.

timeout
[in] Maximum time for select to wait, provided in the form of a timeval structure. Set the timeout parameter to NULL for blocking operation.

Return Value

This function returns the total number of socket handles that are ready and contained in the fd_set structures, zero if the time limit expired, or the SOCKET_ERROR if an error occurred. If the return value is SOCKET_ERROR, WSAGetLastError can be used to retrieve a specific error code.

The following table shows a list of possible error codes.

Error code	Description
WSANOTINITIALISED	A successful WSAStartup call must occur before using this function.
WSAEFAULT	The Windows Sockets implementation was unable to allocate needed resources for its internal operations or the readfds, writefds, exceptfds, or timeval parameters are not part of the user address space.
WSAENETDOWN	The network subsystem has failed.
WSAEINVAL	The time-out value is not valid, or all three descriptor parameters were NULL.
WSAEINTR	The socket was closed.
WSAEINPROGRESS	A blocking Winsock call is in progress, or the service provider is still processing a callback function.
WSAENOTSOCK	One of the descriptor sets contains an entry that is not a socket.

Remarks

This function is used to determine the status of one or more sockets. For each socket, the caller can request information on read, write, or error status. The set of sockets for which a given status is requested is indicated by an fd_set structure. The sockets contained within the fd_set structures must be associated with a single service provider. For the purpose of this restriction, sockets are considered to be from the same service provider if the WSAPROTOCOL_INFO structures describing their protocols have the same providerId value. On return, the structures are updated to reflect the subset of these sockets that meet the specified condition. The select function returns the number of sockets meeting the conditions. A set of macros is provided for manipulating an fd_set structure. Although these macros are compatible with those used in the Berkeley software, the underlying representation is completely different.

Note

If a socket is processing a connect call (nonblocking), failure of the connect attempt is indicated in exceptfds (application must then call getsockopt SO_ERROR to determine the error value to describe why the failure occurred). This document does not define which other errors will be included.

The following table shows parameters that can check sockets for read, write, or error status.

Parameter	Description
readfds	Identifies the sockets that will be checked for readability. A socket is considered readable when one of the following conditions is met: listen has been called and a connection is pending. In this case, accept (Windows Sockets) will complete without blocking. Data is available for reading, including out of band (OOB) data if SO_OOBINLINE is enabled. The connection has been closed or terminated. A socket signaled for readability indicates that the next call to accept, recv, recvfrom, WSARecv, or WSARecvFrom is guaranteed not to block. For connection-oriented sockets, readability can also indicate that a request to close the socket has been received from the peer. If the virtual circuit was closed gracefully, and all data was received, a recv will return immediately with zero bytes read. If the virtual circuit was reset, a recv will complete immediately with an error code such as WSAECONNRESET.
writefds	Identifies the sockets that will be checked for writability. A socket is considered writeable when one of the following conditions is met: The socket is processing a connect call (nonblocking) and the connection suceeds. Data can be sent. A socket signalled for writeability means that the next call to send, sendto, WSASend, or WSASendTo function will probably not block. If the length of data to be sent exceeds the amount of outgoing system buffer space that is available, the call can block on a blocking socket.
exceptfds	Identifies the sockets that will be checked for the following exceptional conditions: The socket is processing a connect call (nonblocking) and the connection attempt fails. OOB data is available for reading if SO_OOBINLINE is disabled. An error occurred with an ongoing, nonblocking operation. The socket is in an error state, for example, the socket has been closed.

readfds

Identifies the sockets that will be checked for readability. A socket is considered readable when one of the following conditions is met:

listen has been called and a connection is pending. In this case, accept (Windows Sockets) will complete without blocking.
Data is available for reading, including out of band (OOB) data if SO_OOBINLINE is enabled.
The connection has been closed or terminated.

A socket signaled for readability indicates that the next call to accept, recv, recvfrom, WSARecv, or WSARecvFrom is guaranteed not to block.

For connection-oriented sockets, readability can also indicate that a request to close the socket has been received from the peer. If the virtual circuit was closed gracefully, and all data was received, a recv will return immediately with zero bytes read. If the virtual circuit was reset, a recv will complete immediately with an error code such as WSAECONNRESET.

writefds

Identifies the sockets that will be checked for writability. A socket is considered writeable when one of the following conditions is met:

The socket is processing a connect call (nonblocking) and the connection suceeds.
Data can be sent.

A socket signalled for writeability means that the next call to send, sendto, WSASend, or WSASendTo function will probably not block. If the length of data to be sent exceeds the amount of outgoing system buffer space that is available, the call can block on a blocking socket.

exceptfds

Identifies the sockets that will be checked for the following exceptional conditions:

The socket is processing a connect call (nonblocking) and the connection attempt fails.
OOB data is available for reading if SO_OOBINLINE is disabled.
An error occurred with an ongoing, nonblocking operation.
The socket is in an error state, for example, the socket has been closed.

Any two of the parameters, readfds, writefds, or exceptfds, can be given as NULL. At least one must be non-NULL, and any non-NULL descriptor set must contain at least one handle to a socket.

Four macros are defined in the header file Winsock2.h for manipulating and checking the descriptor sets. The variable FD_SETSIZE determines the maximum number of descriptors in a set. (The default value of FD_SETSIZE is 64, which can be modified by defining FD_SETSIZE to another value before including Winsock2.h.) Internally, socket handles in an fd_set structure are not represented as bit flags as in Berkeley Unix. Their data representation is opaque. Use of these macros will maintain software portability between different socket environments. The following macros manipulate and check fd_set contents:

FD_CLR(s, *set)

Note

Removes descriptor s from set.

FD_ISSET(s, *set)

Note

Nonzero if s is a member of the set. Otherwise, zero.

FD_SET(s, *set)

Note

Adds descriptor s to set.

FD_ZERO(*set)

Note

Initializes the set to the NULL set.

The timeout parameter controls how long the select can take to complete. If timeout is a NULL pointer, select will block indefinitely until at least one descriptor meets the specified criteria. Otherwise, timeout points to a timeval structure that specifies the maximum time that select should wait before returning. When select returns, the contents of the timeval structure are not altered. If timeval is initialized to {0, 0}, select will return immediately; this is used to poll the state of the selected sockets. If select returns immediately, then the select call is considered nonblocking and the standard assumptions for nonblocking calls apply. For example, the blocking hook will not be called and Windows Sockets will not yield.

Note

The select function has no effect on the persistence of socket events registered with WSAEventSelect.

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

select

Syntax

Parameters

Return Value

Remarks

Requirements

See Also

Reference

Additional resources