_findfirst, _wfindfirst

Artigo
02/25/2013

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

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 (podem incluir caracteres curinga).
fileinfo
Buffer de informações do arquivo.

Valor de retorno

Se for bem-sucedido, _findfirst retorna um identificador de pesquisa exclusiva que identifica o arquivo ou grupo de arquivos que correspondem a filespec especificação, que pode ser usada em uma chamada subseqüente para _findnext ou para _findclose.Caso contrário, _findfirst retorna – 1 e define errno a um dos seguintes valores.

EINVAL
Invalid parameter: filespec or fileinfo was NULL.Ou então, 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 do nome de arquivo inválido ou o nome de arquivo dado era maior do que MAX_PATH.

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

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

Comentários

Você deve chamar _findclose depois que terminar com um a _findfirst ou _findnext função (ou quaisquer variantes).Isso libera recursos usados por essas funções em seu aplicativo.

As variações dessas funções que têm o w prefixo são versões de caractere largo; Caso contrário, eles são idênticos às funções de byte único correspondentes.

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

Essas funções usarem várias formas do _finddata_t estrutura para o fileinfo parâmetro.Para obter mais informações sobre a estrutura, consulte _find, _wfind funções.

As variações que usam um tipo de tempo de 64 bits permitem que as datas de criação do arquivo a ser expressa até a 23: 59: 59, 31 de dezembro de 3000, a UTC.Aqueles que usam tipos de tempo de 32 bits representam datas somente até 19: 14: 07 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 tenha um motivo específico para usar as versões que especifique o tamanho de tempo explicitamente, use _findfirst ou _wfindfirst ou, se você precisar suportar tamanhos de arquivo maiores do que 3 GB, use _findfirsti64 ou _wfindfirsti64.Todas essas funções usam o tipo de tempo de 64 bits.Nas versões anteriores, essas funções usadas de um tipo de tempo de 32 bits.Se esta for uma alteração significativa para um aplicativo, você pode definir _USE_32BIT_TIME_T para reverter para o comportamento antigo.Se _USE_32BIT_TIME_T for definido, _findfirst, _finfirsti64, e suas versões correspondentes do Unicode usem um horário de 32 bits.

Tipo de tempo e variações de tipo de tamanho de arquivo de _findfirst

Funções	_USE_32BIT_TIME_Tdefinido?	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 é afetada pela definição de macro	32 bits	32 bits
_findfirst64, _wfindfirst64	Não é afetada 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 é afetada pela definição de macro	32 bits	64 bits
_findfirst64i32, _wfindfirst64i32	Não é afetada pela definição de macro	64 bits	32 bits

Mapeamentos de rotina de texto genérico

Rotina de TCHAR.h	_ Unicode e _ MBCS do arquivo não definido	_ MBCS do arquivo 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>