_findfirst, _wfindfirst

Artigo
06/09/2015

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

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
O buffer de informações do Arquivo.

Valor de retorno

Se tiver êxito, _findfirst retorna um identificador exclusivo de pesquisa que identifica o arquivo ou grupo de arquivos que correspondem a especificação de filespec , que pode ser usada em uma chamada subsequente a _findnext ou a _findclose. Caso contrário, _findfirst 1 será retornado e define errno a um dos valores a seguir.

EINVAL
Parâmetro inválido: filespec ou fileinfo foram NULL. Ou, o sistema operacional retornou um erro inesperado.
ENOENT
Especificação de Arquivo que não pôde ser comparada.
ENOMEM
Memória insuficiente.
EINVAL
A especificação inválida de nome de arquivo ou o nome de arquivo determinado era maior que MAX_PATH.

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

Se um parâmetro inválido é passado, essas funções invoca o manipulador inválido do parâmetro, conforme descrito em Validação do parâmetro.

Comentários

Você deve chamar _findclose depois de concluir a _findfirst ou função de _findnext (ou algumas variantes). Isso libera os recursos usados por essas funções em seu aplicativo.

Variações dessas funções que têm o prefixo de w são versões de ampla caractere; caso contrário, o valor é idêntico a funções correspondentes de um byte.

Variações dessas funções oferecem suporte a tipos de 32 bits ou de 64 bits de tempo e tamanhos de arquivos de 32 bits 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, e indica se o tamanho do arquivo é representado como um inteiro de 32 bits ou de 64 bits. Para obter informações sobre as versões oferecem suporte aos tipos de 32 bits e de 64 bits e os tamanhos de arquivos de tempo, consulte a tabela a seguir. O sufixo de i32 ou de i64 for omitida se for igual ao tamanho do tipo de tempo, para que _findfirst64 também oferece suporte aos comprimentos de 64 bits do arquivo e _findfirst32 da suporte somente aos comprimentos de 32 bits do arquivo.

Esses formulários de uso de funções múltiplas da estrutura de _finddata_t para o parâmetro de fileinfo . Para obter mais informações sobre a estrutura, consulte Funções _find, _wfind.

Variações que usam um tipo de 64 bits de tempo habilita as datas de arquivo criar com base anterior a 23:59: o 31 de dezembro, 59, 3000, UTC. Os que usam tipos de 32 bits de hora atuais representarem datas somente a 19:14: 7 de janeiro de 18, 2038, UTC. A meia-noite, o 1º de janeiro de 1970, é o limite inferior do intervalo de datas para todas essas funções.

A menos que você tenha uma razão específica usar as versões que especificam o tamanho de tempo explicitamente, use _findfirst ou _wfindfirst ou, se você precisar dar suporte a tamanhos de arquivos de 3 GB maior, para usar _findfirsti64 ou _wfindfirsti64. Todas essas funções usam o tipo de 64 bits de tempo. Em versões anteriores, essas funções usam um tipo de 32 bits de tempo. Se esta é uma alteração de quebra para um aplicativo, você pode definir _USE_32BIT_TIME_T para reverter para o comportamento antigo. Se _USE_32BIT_TIME_T é definido, _findfirst, _finfirsti64, e as versões correspondentes Unicode usam um horário de 32 bits.

Hora em que o tipo e arquiva variações do tipo de comprimento de _findfirst

Funções	_USE_32BIT_TIME_T definido?	Tipo de tempo	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 macro	32 bits	32 bits
_findfirst64, _wfindfirst64	Não afetado pela definição 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 macro	32 bits	64 bits
_findfirst64i32, _wfindfirst64i32	Não afetado pela definição macro	64 bits	32 bits

Mapeamentos da 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 <>