_findfirst, _findfirst32, _findfirst32i64, _findfirst64, _findfirst64i32, _findfirsti64, _wfindfirst, _wfindfirst32, _wfindfirst32i64, _wfindfirst64, _wfindfirst64i32, _wfindfirsti64

Forneça informações sobre a primeira instância de um nome de arquivo que corresponde ao arquivo especificado no argumento filespec.

Sintaxe

intptr_t _findfirst(
   const char *filespec,
   struct _finddata_t *fileinfo
);
intptr_t _findfirst32(
   const char *filespec,
   struct _finddata32_t *fileinfo
);
intptr_t _findfirst64(
   const char *filespec,
   struct _finddata64_t *fileinfo
);
intptr_t _findfirsti64(
   const char *filespec,
   struct _finddatai64_t *fileinfo
);
intptr_t _findfirst32i64(
   const char *filespec,
   struct _finddata32i64_t *fileinfo
);
intptr_t _findfirst64i32(
   const char *filespec,
   struct _finddata64i32_t *fileinfo
);
intptr_t _wfindfirst(
   const wchar_t *filespec,
   struct _wfinddata_t *fileinfo
);
intptr_t _wfindfirst32(
   const wchar_t *filespec,
   struct _wfinddata32_t *fileinfo
);
intptr_t _wfindfirst64(
   const wchar_t *filespec,
   struct _wfinddata64_t *fileinfo
);
intptr_t _wfindfirsti64(
   const wchar_t *filespec,
   struct _wfinddatai64_t *fileinfo
);
intptr_t _wfindfirst32i64(
   const wchar_t *filespec,
   struct _wfinddata32i64_t *fileinfo
);
intptr_t _wfindfirst64i32(
   const wchar_t *filespec,
   struct _wfinddata64i32_t *fileinfo
);

Parâmetros

filespec
Especificação de arquivo de destino (pode incluir caracteres curinga).

fileinfo
Buffer de informações do arquivo.

Retornar valor

Se bem-sucedido, _findfirst retornará um identificador de pesquisa exclusivo que identificará o arquivo ou o grupo de arquivos que corresponderem à especificação filespec, que poderá ser usado em uma chamada subsequente para _findnext ou _findclose. Caso contrário, _findfirst retornará - 1 e definirá errno como um dos valores a seguir.

Valor de errno	Condição
EINVAL	Parâmetro inválido: filespec ou fileinfo era NULL. Ou o sistema operacional retornou um erro inesperado.
ENOENT	Especificação de arquivo que não pôde ser correspondida.
ENOMEM	Memória insuficiente.
EINVAL	Especificação de nome de arquivo inválida ou o nome de arquivo fornecido era maior que MAX_PATH.

Para obter mais informações sobre esses e outros códigos de retorno, confira errno, _doserrno, _sys_errlist e _sys_nerr.

Se um parâmetro inválido for passado, essas funções invocarão o manipulador de parâmetros inválido, conforme descrito em Validação de parâmetro.

Comentários

Você deve ligar _findclose depois de terminar com a função ou (ou _findnext quaisquer variantes) desde que a _findfirst chamada _findfirst seja bem-sucedida. _findclose Libera recursos usados por essas funções em seu aplicativo. Chamar _findclose um identificador inválido retorna -1 e define errno como EINVAL.

As variações dessas funções que têm o prefixo w são versões de caracteres largos, caso contrário, elas são idênticas às funções de byte único correspondentes.

Variações dessas funções dão suporte a tipos de hora de 32 ou de 64 bits e a tamanhos de arquivo de 32 ou de 64 bits. O primeiro sufixo numérico (32 ou 64) indica o tamanho do tipo de hora; o segundo sufixo é i32 ou i64, que indica se o tamanho do arquivo é representado como um inteiro de 32 ou de 64 bits. Para obter informações sobre quais versões dão suporte a tamanhos de arquivo e tipos de hora de 32 e de 64 bits, consulte a tabela a seguir. O i32 sufixo ou i64 é omitido se for igual ao tamanho do tipo de tempo, portanto _findfirst64 , também oferece suporte a comprimentos de arquivo de 64 bits e _findfirst32 suporta apenas comprimentos de arquivo de 32 bits.

Essas funções usam várias formas da estrutura _finddata_t para o parâmetro fileinfo. Para obter mais informações sobre a estrutura, consulte Funções de pesquisa de nome de arquivo.

As variações que usam um tipo de hora de 64 bits permitem que as datas de criação de arquivo sejam expressas até 23:59:59 de 31 de dezembro de 3000, no horário UTC. Os que usam tipos de tempo de 32 bits representam datas apenas até 23:59:59 de 18 de janeiro de 2038, UTC. Meia-noite de 1º de janeiro de 1970 é o limite inferior do intervalo de datas para todas essas funções.

A menos que você tenha um motivo específico para usar as versões que especificam o tamanho da hora explicitamente, use _findfirst ou _wfindfirst. Se precisar dar suporte a tamanhos de arquivos de mais de 3 GB, use _findfirsti64 ou _wfindfirsti64. Todas essas funções usam o tipo de hora de 64 bits. Em versões anteriores, elas usavam um tipo de hora de 32 bits. Se essa alteração for uma alteração de interrupção para um aplicativo, você poderá definir _USE_32BIT_TIME_T para reverter para o comportamento antigo. Se _USE_32BIT_TIME_T for definido, _findfirst, _finfirsti64 e suas versões Unicode correspondentes usarão uma hora de 32 bits.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, consulte Estado global na CRT.

Variações de tipo de hora e tipo de tamanho de arquivo de _findfirst

Funções	_USE_32BIT_TIME_T definido?	Tipo de hora	Tipo de tamanho de arquivo
_findfirst, _wfindfirst	Não definido	64 bits	32 bits
_findfirst, _wfindfirst	Definido	32 bits	32 bits
_findfirst32, _wfindfirst32	Não afetado pela definição de macro	32 bits	32 bits
_findfirst64, _wfindfirst64	Não afetado pela definição de macro	64 bits	64 bits
_findfirsti64, _wfindfirsti64	Não definido	64 bits	64 bits
_findfirsti64, _wfindfirsti64	Definido	32 bits	64 bits
_findfirst32i64, _wfindfirst32i64	Não afetado pela definição de macro	32 bits	64 bits
_findfirst64i32, _wfindfirst64i32	Não afetado pela definição de macro	64 bits	32 bits

Mapeamentos de rotina de texto genérico

Rotina Tchar.h	_UNICODE e _MBCS não definidos	_MBCS definido	_UNICODE definido
_tfindfirst	_findfirst	_findfirst	_wfindfirst
_tfindfirst32	_findfirst32	_findfirst32	_wfindfirst32
_tfindfirst64	_findfirst64	_findfirst64	_wfindfirst64
_tfindfirsti64	_findfirsti64	_findfirsti64	_wfindfirsti64
_tfindfirst32i64	_findfirst32i64	_findfirst32i64	_wfindfirst32i64
_tfindfirst64i32	_findfirst64i32	_findfirst64i32	_wfindfirst64i32

Requisitos

Função	Cabeçalho necessário
_findfirst	<io.h>
_findfirst32	<io.h>
_findfirst64	<io.h>
_findfirsti64	<io.h>
_findfirst32i64	<io.h>
_findfirst64i32	<io.h>
_wfindfirst	<io.h> ou <wchar.h>
_wfindfirst32	<io.h> ou <wchar.h>
_wfindfirst64	<io.h> ou <wchar.h>
_wfindfirsti64	<io.h> ou <wchar.h>
_wfindfirst32i64	<io.h> ou <wchar.h>
_wfindfirst64i32	<io.h> ou <wchar.h>

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Confira também

Chamadas do sistema
Funções de pesquisa de nome de arquivo