_findfirst, _wfindfirst

Article
06/09/2015

Fournit des informations à propos de la première instance d'un nom de fichier correspondant au fichier spécifié dans l'argument 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 
);

Paramètres

filespec
Spécification du fichier cible (peut comprendre des caractères génériques).
fileinfo
Mémoire tampon de l'Information fichier.

Valeur de retour

En cas de réussite, _findfirst retourne un descripteur unique de recherche qui identifie le fichier ou l'ensemble de fichiers qui correspondent à la spécification filespec, qui peut être utilisée dans l'appel suivant à _findnext ou à _findclose. Sinon, _findfirst retourne – 1 et affecte errno à l'une des valeurs suivantes.

EINVAL
Paramètre non valide: filespec ou fileinfo était NULL. Ou, le système d'exploitation a retourné une erreur inattendue.
ENOENT
Spécification de fichiers qui ne peut pas être mise en correspondance.
ENOMEM
Mémoire insuffisante.
EINVAL
Spécification de nom de fichier invalide ou le nom du fichier donné est plus grand que MAX_PATH.

Pour plus d'informations sur ces codes de retour et autres, consultez _doserrno, errno, _sys_errlist et _sys_nerr.

Si un paramètre non valide a été passé, ces fonctions appellent le gestionnaire de paramètre non valide, comme décrit dans Validation de paramètre.

Notes

Vous devez appeler _findclose au terme de l'utilisation de la fonction _findfirst ou de la fonction _findnext (ou toutes variantes). Cela libère les ressources utilisées par ces fonctions dans votre application.

Les variations de ces fonctions qui ont le préfixe w sont des versions de caractères larges ; sinon, elles sont identiques aux fonctions codées sur un octet correspondantes.

Les variations de ces fonctions prennent en charge les types d'heure 32 bits ou 64 bits et les fichiers de taille 32 bits ou 64 bits. Le premier suffixe numérique (32 ou 64) indique la taille du type de temps utilisé ; le deuxième suffixe est i32 ou i64, et indique si la taille du fichier est représentée comme un entier 32 bits ou 64 bits. Pour plus d'informations sur quelles versions prennent en charge les types d'heure 32 bits et 64 bits et les tailles de fichiers, consultez le tableau suivant. Le suffixe i32 ou i64 est omis si c'est le même que la taille du type d'heure, donc _findfirst64 prend également en charge les fichiers de longueur 64 bits et _findfirst32 prend en charge les fichiers de longueur 32 bits..

Ces fonctions utilisent des formes variées de la structure _finddata_t pour le paramètre fileinfo. Pour plus d'informations sur la structure, consultez _find, _wfind, fonctions.

Les variations qui utilisent un type d'heure 64 bits permettent aux dates de création de fichier d'être exprimées à 23h59 : 59, le 31 décembre, 3000, UTC. Ceux qui utilisent les types d'heure 32 bits représentent les dates uniquement à 19h14:07 Le 18 janvier, 2038, les valeurs UTC. Minuit, le 1er janvier 1970, est la limite inférieure de la plage de dates pour ces deux fonctions.

À moins d'avoir une raison particulière d'utiliser les versions qui spécifient la taille de temps explicitement, utilisez _findfirst ou _wfindfirst ou, si vous avez besoin de supporter des tailles de fichier supérieures à 3Go , utilisez _findfirsti64 ou _wfindfirsti64. Toutes ces fonctions utilisent le type d'heure 64 bits. Dans les versions antérieures, ces fonctions ont utilisé le type d'heure 32 bits. S'il s'agit d'une modification importante pour une application, vous pouvez définir _USE_32BIT_TIME_T pour revenir au comportement antérieur. Si _USE_32BIT_TIME_T est défini, _findfirst, _finfirsti64 et leurs versions correspondantes Unicode utilisent une heure 32 bits.

Type d'Heure et Variation du Type de Longueur de Fichier de _findfirst

Fonctions	_USE_32BIT_TIME_T défini?	Type de Temps	Type de taille de fichier
_findfirst, _wfindfirst	Non défini	64 bits	32 bits
_findfirst, _wfindfirst	(défini par)	32 bits	32 bits
_findfirst32, _wfindfirst32	Non affecté par la définition de macro	32 bits	32 bits
_findfirst64, _wfindfirst64	Non affecté par la définition de macro	64 bits	64 bits
_findfirsti64, _wfindfirsti64	Non défini	64 bits	64 bits
_findfirsti64, _wfindfirsti64	(défini par)	32 bits	64 bits
_findfirst32i64, _wfindfirst32i64	Non affecté par la définition de macro	32 bits	64 bits
_findfirst64i32, _wfindfirst64i32	Non affecté par la définition de macro	64 bits	32 bits

Mappages de routines de texte générique

Routine Tchar.h	_UNICODE et _MBCS non définis	_MBCS défini	_UNICODE défini
_tfindfirst	_findfirst	_findfirst	_wfindfirst
_tfindfirst32	_findfirst32	_findfirst32	_wfindfirst32
_tfindfirst64	_findfirst64	_findfirst64	_wfindfirst64
_tfindfirsti64	_findfirsti64	_findfirsti64	_wfindfirsti64
_tfindfirst32i64	_findfirst32i64	_findfirst32i64	_wfindfirst32i64
_tfindfirst64i32	_findfirst64i32	_findfirst64i32	_wfindfirst64i32

Configuration requise

Fonction	En-tête requis
_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>