função select (winsock2.h)

A função select determina o status de um ou mais soquetes, aguardando, se necessário, para executar E/S síncrona.

Sintaxe

int WSAAPI select(
  [in]      int           nfds,
  [in, out] fd_set        *readfds,
  [in, out] fd_set        *writefds,
  [in, out] fd_set        *exceptfds,
  [in]      const timeval *timeout
);

Parâmetros

[in] nfds

Ignorado. O parâmetro nfds é incluído apenas para compatibilidade com soquetes berkeley.

[in, out] readfds

Um ponteiro opcional para um conjunto de soquetes a ser verificado quanto à legibilidade.

[in, out] writefds

Um ponteiro opcional para um conjunto de soquetes a ser verificado quanto à gravabilidade.

[in, out] exceptfds

Um ponteiro opcional para um conjunto de soquetes a serem verificados quanto a erros.

[in] timeout

O tempo máximo para selecionar aguardar, fornecido na forma de uma estrutura TIMEVAL . Defina o parâmetro de tempo limite como nulo para operações de bloqueio.

Valor de retorno

A função select retorna o número total de identificadores de soquete que estão prontos e contidos nas estruturas de fd_set , zero se o limite de tempo expirou ou SOCKET_ERROR se ocorreu um erro. Se o valor retornado for SOCKET_ERROR, o WSAGetLastError poderá ser usado para recuperar um código de erro específico.

Código do erro	Meaning
WSANOTINITIALISED	Uma chamada WSAStartup bem-sucedida deve ocorrer antes de usar essa função.
WSAEFAULT	A implementação do Windows Sockets não pôde alocar os recursos necessários para suas operações internas ou os readfds, writefds, exceptfds ou parâmetros de valor de tempo não fazem parte do espaço de endereço do usuário.
WSAENETDOWN	O subsistema de rede falhou.
WSAEINVAL	WSAEINVAL será retornado se o valor de tempo limite for inválido ou se todos os três parâmetros de descritor forem ponteiros nulos ou ponteiros válidos para estruturas de fd_set vazias sem soquetes.
WSAEINTR	Uma chamada de bloqueio do Windows Socket 1.1 foi cancelada por meio de WSACancelBlockingCall.
WSAEINPROGRESS	Uma chamada de bloqueio do Windows Sockets 1.1 está em andamento ou o provedor de serviços ainda está processando uma função de retorno de chamada.
WSAENOTSOCK	Um dos conjuntos de descritores contém uma entrada que não é um soquete.

Observações

A função select é usada para determinar o status de um ou mais soquetes. Para cada soquete, o chamador pode solicitar informações sobre o status de leitura, gravação ou erro. O conjunto de soquetes para o qual um determinado status é solicitado é indicado por uma estrutura de fd_set . Os soquetes contidos nas estruturas de fd_set devem ser associados a um único provedor de serviços. Para fins dessa restrição, os soquetes são considerados do mesmo provedor de serviços se as estruturas de WSAPROTOCOL_INFO que descrevem seus protocolos tiverem o mesmo valor providerId . Após o retorno, as estruturas são atualizadas para refletir o subconjunto desses soquetes que atendem à condição especificada. A função select retorna o número de soquetes que atendem às condições. Um conjunto de macros é fornecido para manipular uma estrutura de fd_set . Essas macros são compatíveis com as usadas no software berkeley, mas a representação subjacente é completamente diferente.

Os readfds de parâmetro identificam os soquetes que devem ser verificados quanto à legibilidade. Se o soquete estiver atualmente no estado de escuta , ele será marcado como legível se uma solicitação de conexão de entrada tiver sido recebida, de modo que uma aceitação seja garantida para ser concluída sem bloqueio. Para outros soquetes, a legibilidade significa que os dados enfileirados estão disponíveis para leitura de modo que uma chamada para recv, WSARecv, WSARecvFrom ou revfrom seja garantida para não bloquear.

Para soquetes orientados à conexão, a legibilidade também pode indicar que uma solicitação para fechar o soquete foi recebida do par. Se o circuito virtual foi fechado normalmente e todos os dados foram recebidos, um recv retornará imediatamente com zero bytes lidos. Se o circuito virtual tiver sido redefinido, um recv será concluído imediatamente com um código de erro, como WSAECONNRESET. A presença de dados OOB será verificada se a opção de soquete SO_OOBINLINE foi habilitada (consulte setsockopt).

Os writefds de parâmetro identificam os soquetes que devem ser verificados quanto à gravabilidade. Se um soquete estiver processando uma chamada de conexão (sem bloqueio), um soquete será gravável se o estabelecimento de conexão for concluído com êxito. Se o soquete não estiver processando uma chamada de conexão , a gravabilidade significará que um envio, envio ou WSASendto têm a garantia de êxito. No entanto, eles podem bloquear em um soquete de bloqueio se o parâmetro len exceder a quantidade de espaço de buffer do sistema de saída disponível. Não é especificado por quanto tempo essas garantias podem ser consideradas válidas, especialmente em um ambiente multithread.

O parâmetro exceptfds identifica os soquetes que devem ser verificados quanto à presença de dados OOB ou quaisquer condições de erro excepcionais.

Nota Os dados fora de banda só serão relatados dessa forma se a opção SO_OOBINLINE for FALSE. Se um soquete estiver processando uma chamada de conexão (sem bloqueio), a falha da tentativa de conexão será indicada em exceptfds (o aplicativo deve chamar getsockopt SO_ERROR para determinar o valor do erro para descrever por que a falha ocorreu). Este documento não define quais outros erros serão incluídos.

Qualquer um dos dois parâmetros, readfds, writefds ou exceptfds, pode ser dado como nulo. Pelo menos um deve ser não nulo e qualquer conjunto de descritor não nulo deve conter pelo menos um identificador para um soquete.

Em resumo, um soquete será identificado em um determinado conjunto quando a seleção retornar se:

readfds:

Se a escuta tiver sido chamada e uma conexão estiver pendente, a aceitação terá êxito.
Os dados estarão disponíveis para leitura (inclui dados OOB se SO_OOBINLINE estiver habilitado).
A conexão foi fechada/redefinida/encerrada.

writefds:

Se estiver processando uma chamada de conexão (sem bloqueio), a conexão terá sido bem-sucedida.
Os dados podem ser enviados.

exceptfds:

Se estiver processando uma chamada de conexão (sem bloqueio), a tentativa de conexão falhará.
Os dados do OOB estão disponíveis para leitura (somente se SO_OOBINLINE estiver desabilitado).

Quatro macros são definidas no arquivo de cabeçalho Winsock2.h para manipular e verificar os conjuntos de descritores. A variável FD_SETSIZE determina o número máximo de descritores em um conjunto. (O valor padrão de FD_SETSIZE é 64, que pode ser modificado definindo FD_SETSIZE para outro valor antes de incluir Winsock2.h.) Internamente, os identificadores de soquete em uma estrutura fd_set não são representados como sinalizadores de bits como no Berkeley Unix. A representação de dados deles é opaca. O uso dessas macros manterá a portabilidade do software entre diferentes ambientes de soquete. As macros para manipular e verificar fd_set conteúdo são:

FD_ZERO(*set) – Inicializa definido como o conjunto vazio. Um conjunto sempre deve ser limpo antes de usar.
FD_CLR(s, *set) – Remove os soquetes do conjunto.
FD_ISSET(s, *set) – Verifica se s é um membro do conjunto e retorna TRUE se sim.
FD_SET(s, *set) – adiciona soquetes a serem definidos.

O tempo limite do parâmetro controla quanto tempo a seleção pode levar para ser concluída. Se o tempo limite for um ponteiro nulo , a seleção será bloqueada indefinidamente até que pelo menos um descritor atenda aos critérios especificados. Caso contrário, o tempo limite aponta para uma estrutura TIMEVAL que especifica o tempo máximo que a seleção deve aguardar antes de retornar. Quando a seleção é retornada, o conteúdo da estrutura TIMEVAL não é alterado. Se TIMEVAL for inicializado como {0, 0}, a seleção retornará imediatamente; isso é usado para sondar o estado dos soquetes selecionados. Se a seleção retornar imediatamente, a chamada selecionada será considerada não desbloqueado e as suposições padrão para chamadas sem bloqueio serão aplicadas. Por exemplo, o gancho de bloqueio não será chamado e os Soquetes do Windows não renderão.

Nota A função select não tem efeito sobre a persistência de eventos de soquete registrados com WSAAsyncSelect ou WSAEventSelect.

Nota Ao emitir uma chamada winsock de bloqueio, como selecionar com o parâmetro de tempo limite definido como NULL, Winsock pode precisar aguardar um evento de rede antes que a chamada possa ser concluída. O Winsock executa uma espera alertável nessa situação, que pode ser interrompida por uma APC (chamada de procedimento assíncrono) agendada no mesmo thread. A emissão de outra chamada winsock de bloqueio dentro de um APC que interrompeu uma chamada Winsock de bloqueio contínuo no mesmo thread levará a um comportamento indefinido e nunca deve ser tentada pelos clientes winsock.

Windows Phone 8: Essa função tem suporte para aplicativos da Windows Phone Store no Windows Phone 8 e posteriores.

Windows 8.1 e Windows Server 2012 R2: essa função tem suporte para aplicativos da Windows Store no Windows 8.1, Windows Server 2012 R2 e posterior.

Requirements

Requirement	Value
Cliente mínimo suportado	Windows 8.1, Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo compatível	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
Header	winsock2.h
Library	Ws2_32.lib
de DLL	Ws2_32.dll

Consulte também

Referência de Winsock

Comentários

Esta página foi útil?

Last updated on 2025-12-18