_findfirst, _findfirst32, _findfirst32i64, _findfirst64, _findfirst64i32, _findfirsti64, _wfindfirst, _wfindfirst32_wfindfirst32i64_wfindfirst64_wfindfirst64i32_wfindfirsti64

Proporcione información sobre la primera instancia de un nombre de archivo que coincide con el archivo especificado en el argumento filespec.

Sintaxis

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
Especificación de archivo de destino (puede incluir caracteres comodín).

fileinfo
Búfer de información de archivo. Para obtener más información sobre las fileinfo estructuras, vea los comentarios en funciones de búsqueda de nombre de archivo y vea Asignaciones de tipos de datos. Las estructuras se definen en el mismo archivo de encabezado que la función que los usa como parámetro.

Valor devuelto

Si se realiza correctamente, _findfirst devuelve un identificador de búsqueda exclusivo que identifica el archivo o grupo de archivos que coinciden con la especificación filespec, que puede usarse en una llamada posterior a _findnext o _findclose. De lo contrario, _findfirst devuelve -1 y establece errno en uno de los valores siguientes.

Valor de errno	Condición
EINVAL	Parámetro no válido: filespec o fileinfo era NULL. O bien, el sistema operativo ha devuelto un error inesperado.
ENOENT	Especificación de archivo que no se pudo coincidir.
ENOMEM	Memoria suficiente.
EINVAL	Especificación del nombre de archivo no válido o el nombre de archivo indicado era mayor que MAX_PATH.

Para obtener más información sobre estos y otros códigos de retorno, vea errno, _doserrno, _sys_errlist y _sys_nerr.

Si se pasa un parámetro no válido, estas funciones invocan al controlador de parámetros no válidos, como se describe en Validación de parámetros.

Comentarios

Debe llamar _findclose a después de que haya terminado con la _findfirst función o _findnext (o cualquier variante) siempre que la llamada se _findfirst realice correctamente. _findclose libera recursos usados por estas funciones en la aplicación. La llamada a _findclose en un identificador no válido devuelve -1 y establece en errno EINVAL.

Las variaciones de estas funciones que tienen el w prefijo son versiones de caracteres anchos; de lo contrario, son idénticas a las funciones de un solo byte correspondientes.

Las variaciones de estas funciones admiten tipos de tiempo de 32 o 64 bits y tamaños de archivos de 32 o 64 bits. El primer sufijo numérico (32 o 64) indica el tamaño del tipo de tiempo usado; el segundo sufijo es i32 o i64, lo que indica si el tamaño del archivo se representa como un entero de 32 o 64 bits. Para obtener información sobre las versiones que admiten tipos de tiempo y tamaños de archivo de 32 bits y 64 bits, consulte la tabla siguiente. El i32 sufijo o i64 se omite si es el mismo que el tamaño del tipo de tiempo, por lo que _findfirst64 también admite longitudes de archivo de 64 bits y _findfirst32 solo admite longitudes de archivo de 32 bits.

Estas funciones usan diversas formas de la estructura _finddata_t para el parámetro fileinfo. Para obtener más información sobre la estructura, vea Funciones de búsqueda de nombre de archivo.

Las variaciones que usan un tipo de tiempo de 64 bits permiten expresar fechas de creación de archivos hasta las 23:59:59 horas del 31 de diciembre de 3000, UTC. Los que usan tipos de tiempo de 32 bits representan solo fechas a las 23:59:59: 18 de enero de 2038, UTC. La medianoche del 1 de enero de 1970 es el límite inferior del intervalo de fechas para todas estas funciones.

A menos que tenga una razón concreta para usar las versiones que especifican el tamaño de tiempo de forma explícita, use _findfirst o _wfindfirst; si tiene que admitir tamaños de archivo de más de 3 GB, use _findfirsti64 o _wfindfirsti64. Todas estas funciones usan el tipo de tiempo de 64 bits. En versiones anteriores, estas funciones usan un tipo de tiempo de 32 bits. Si este cambio es un cambio importante para una aplicación, puede definir _USE_32BIT_TIME_T para revertir al comportamiento anterior. Si se define _USE_32BIT_TIME_T, _findfirst, _findfirsti64 y sus correspondientes versiones Unicode usan un tiempo de 32 bits.

De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiar este comportamiento, consulte Estado global en CRT.

Variaciones de tipo de tiempo y tipo de longitud de archivo de _findfirst

Funciones	¿Se ha definido _USE_32BIT_TIME_T?	Tipo de tiempo	Tipo de longitud de archivo
_findfirst, _wfindfirst	No definida	64 bits	32 bits
_findfirst, _wfindfirst	Definido	32 bits	32 bits
_findfirst32, _wfindfirst32	No se ve afectada por la definición de macro	32 bits	32 bits
_findfirst64, _wfindfirst64	No se ve afectada por la definición de macro	64 bits	64 bits
_findfirsti64, _wfindfirsti64	No definida	64 bits	64 bits
_findfirsti64, _wfindfirsti64	Definido	32 bits	64 bits
_findfirst32i64, _wfindfirst32i64	No se ve afectada por la definición de macro	32 bits	64 bits
_findfirst64i32, _wfindfirst64i32	No se ve afectada por la definición de macro	64 bits	32 bits

Asignaciones de rutinas de texto genérico

Rutina Tchar.h	_UNICODE y _MBCS no 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

Función	Encabezado necesario
_findfirst	<io.h>
_findfirst32	<io.h>
_findfirst64	<io.h>
_findfirsti64	<io.h>
_findfirst32i64	<io.h>
_findfirst64i32	<io.h>
_wfindfirst	<io.h> o <wchar.h>
_wfindfirst32	<io.h> o <wchar.h>
_wfindfirst64	<io.h> o <wchar.h>
_wfindfirsti64	<io.h> o <wchar.h>
_wfindfirst32i64	<io.h> o <wchar.h>
_wfindfirst64i32	<io.h> o <wchar.h>

Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Consulte también

Llamadas del sistema
Funciones de búsqueda de nombre de archivo