_findfirst, _findfirst32, _findfirst32i64, _findfirst64, _findfirst64i32_wfindfirst32i64_findfirsti64_wfindfirst64i32_wfindfirst_wfindfirst32_wfindfirst64,_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. Para obter mais informações sobre os fileinfo structs, consulte os Comentários em Funções de pesquisa de nome de arquivo e consulte Mapeamentos de tipo de dados. Os structs são definidos no mesmo arquivo de cabeçalho que a função que os usa como parâmetro.

Valor retornado

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.

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âmetro inválido, conforme descrito em Validação de parâmetro.

Comentários

Você deve chamar _findclose depois de terminar com a _findfirst função ou _findnext (ou quaisquer variantes), desde que a chamada seja _findfirst 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 or i64 será omitido se for igual ao tamanho do tipo de hora, portanto _findfirst64 , também dá suporte a comprimentos de arquivo de 64 bits e _findfirst32 dá suporte apenas a 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. Aqueles que usam tipos de hora 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 significativa para um aplicativo, você poderá definir _USE_32BIT_TIME_T a reversão para o comportamento antigo. Se _USE_32BIT_TIME_T for definido, _findfirst, _findfirsti64 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, confira Estado global no CRT.

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

Mapeamentos de rotina de texto genérico

Requisitos

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

Confira também

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