Función FindFirstFileA (fileapi.h)

Busca en un directorio un archivo o subdirectorio con un nombre que coincida con un nombre específico (o un nombre parcial si se usan caracteres comodín).

Para especificar atributos adicionales que se van a usar en una búsqueda, use la función FindFirstFileEx .

Para realizar esta operación como una operación de transacción, use la función FindFirstFileTransacted .

Sintaxis

HANDLE FindFirstFileA(
  [in]  LPCSTR             lpFileName,
  [out] LPWIN32_FIND_DATAA lpFindFileData
);

Parámetros

[in] lpFileName

Directorio o ruta de acceso, y el nombre de archivo. El nombre de archivo puede incluir caracteres comodín, por ejemplo, un asterisco (*) o un signo de interrogación (?).

Este parámetro no debe ser NULL, una cadena no válida (por ejemplo, una cadena vacía o una cadena que falta el carácter nulo de terminación) o terminar en una barra diagonal inversa final (\).

Si la cadena termina con un carácter comodín, un punto (.) o un nombre de directorio, el usuario debe tener permisos de acceso a la raíz y a todos los subdirectorios de la ruta de acceso.

De forma predeterminada, el nombre está limitado a MAX_PATH caracteres. Para ampliar este límite a 32 767 caracteres anchos, anteponga "\\?\\ " a la ruta de acceso. Para obtener más información, vea Nomenclatura de archivos, rutas de acceso y espacios de nombres.

[out] lpFindFileData

Puntero a la estructura WIN32_FIND_DATA que recibe información sobre un archivo o directorio encontrado.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un identificador de búsqueda usado en una llamada posterior a FindNextFile o FindClose, y el parámetro lpFindFileData contiene información sobre el primer archivo o directorio encontrado.

Si se produce un error en la función o no se encuentran los archivos de la cadena de búsqueda en el parámetro lpFileName , el valor devuelto se INVALID_HANDLE_VALUE y el contenido de lpFindFileData es indeterminado. Para obtener información ampliada de los errores, llame a la función GetLastError.

Si se produce un error en la función porque no se encuentra ningún archivo coincidente, la función GetLastError devuelve ERROR_FILE_NOT_FOUND.

Comentarios

La función FindFirstFile abre un identificador de búsqueda y devuelve información sobre el primer archivo que el sistema de archivos encuentra con un nombre que coincida con el patrón especificado. Esto puede ser o no el primer archivo o directorio que aparece en una aplicación de lista de directorios (por ejemplo, el comando dir) cuando se le asigna el mismo patrón de cadena de nombre de archivo. Esto se debe a que FindFirstFile no realiza ninguna ordenación de los resultados de búsqueda. Para obtener más información, consulte FindNextFile.

En la lista siguiente se identifican otras características de búsqueda:

• La búsqueda se realiza estrictamente en el nombre del archivo, no en atributos como una fecha o un tipo de archivo (para otras opciones, vea FindFirstFileEx).
• La búsqueda incluye los nombres de archivo largo y corto.
• Siempre se produce un error al intentar abrir una búsqueda con una barra diagonal inversa final.
• Pasar una cadena no válida, NULL o cadena vacía para el parámetro lpFileName no es un uso válido de esta función. Los resultados en este caso no están definidos.

Cuando el identificador de búsqueda ya no sea necesario, ciérrelo mediante la función FindClose , no CloseHandle.

Como se indicó anteriormente, no puede usar una barra diagonal inversa final (\) en la cadena de entrada lpFileName para FindFirstFile, por lo que es posible que no sea obvio cómo buscar directorios raíz. Si desea ver archivos u obtener los atributos de un directorio raíz, se aplicarán las siguientes opciones:

• Para examinar los archivos de un directorio raíz, puede usar "C:\*" y recorrer el directorio mediante FindNextFile.
• Para obtener los atributos de un directorio raíz, use la función GetFileAttributes .

En los recursos compartidos de red, puede usar un lpFileName en forma de lo siguiente: "\\Server\Share\*". Sin embargo, no puede usar un lpFileName que apunte al propio recurso compartido; por ejemplo, "\\Server\Share" no es válido.

Para examinar un directorio que no es un directorio raíz, use la ruta de acceso a ese directorio, sin una barra diagonal inversa final. Por ejemplo, un argumento de "C:\Windows" devuelve información sobre el directorio "C:\Windows", no sobre un directorio o archivo en "C:\Windows". Para examinar los archivos y directorios de "C:\Windows", use un lpFileName de "C:\Windows\*".

Tenga en cuenta que algún otro subproceso o proceso podría crear o eliminar un archivo con este nombre entre el momento en que se consulta el resultado y el momento en que actúa sobre la información. Si se trata de una posible preocupación para la aplicación, una posible solución es usar la función CreateFile con CREATE_NEW (que produce un error si el archivo existe) o OPEN_EXISTING (lo que produce un error si el archivo no existe).

Si está escribiendo una aplicación de 32 bits para enumerar todos los archivos de un directorio y la aplicación se puede ejecutar en un equipo de 64 bits, debe llamar a la función Wow64DisableWow64FsRedirection antes de llamar a FindFirstFile y llamar a Wow64RevertWow64FsRedirection después de la última llamada a FindNextFile. Para obtener más información, vea Redirector del sistema de archivos.

Si la ruta de acceso apunta a un vínculo simbólico, el búfer de WIN32_FIND_DATA contiene información sobre el vínculo simbólico, y no del destino.

En Windows 8 y Windows Server 2012, esta función es compatible con las tecnologías siguientes.

Ejemplos

En el siguiente ejemplo de C++ se muestra un uso mínimo de FindFirstFile.

#include <windows.h>
#include <tchar.h>
#include <stdio.h>

void _tmain(int argc, TCHAR *argv[])
{
   WIN32_FIND_DATA FindFileData;
   HANDLE hFind;

   if( argc != 2 )
   {
      _tprintf(TEXT("Usage: %s [target_file]\n"), argv[0]);
      return;
   }

   _tprintf (TEXT("Target file is %s\n"), argv[1]);
   hFind = FindFirstFile(argv[1], &FindFileData);
   if (hFind == INVALID_HANDLE_VALUE) 
   {
      printf ("FindFirstFile failed (%d)\n", GetLastError());
      return;
   } 
   else 
   {
      _tprintf (TEXT("The first file found is %s\n"), 
                FindFileData.cFileName);
      FindClose(hFind);
   }
}

Para obtener otro ejemplo, vea Enumerar los archivos en un directorio.

Requisitos

Vea también

Funciones de administración de archivos

FindClose

FindFirstFileEx

FindFirstFileTransacted

FindNextFile

GetFileAttributes

SetFileAttributes

Vínculos simbólicos

Uso de los encabezados de Windows

WIN32_FIND_DATA