Función SearchPathA (processenv.h)

Busca un archivo especificado en una ruta de acceso especificada.

Sintaxis

DWORD SearchPathA(
  [in, optional]  LPCSTR lpPath,
  [in]            LPCSTR lpFileName,
  [in, optional]  LPCSTR lpExtension,
  [in]            DWORD  nBufferLength,
  [out]           LPSTR  lpBuffer,
  [out, optional] LPSTR  *lpFilePart
);

Parámetros

[in, optional] lpPath

Ruta de acceso en la que se va a buscar el archivo.

Si este parámetro es NULL, la función busca un archivo coincidente mediante una ruta de búsqueda del sistema dependiente del Registro. Para obtener más información, vea la sección Comentarios.

[in] lpFileName

Nombre del archivo que se va a buscar.

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.

[in, optional] lpExtension

Extensión que se va a agregar al nombre de archivo al buscar el archivo. El primer carácter de la extensión de nombre de archivo debe ser un punto (.). La extensión solo se agrega si el nombre de archivo especificado no termina con una extensión.

Si no se requiere una extensión de nombre de archivo o si el nombre de archivo contiene una extensión, este parámetro puede ser NULL.

[in] nBufferLength

Tamaño del búfer que recibe la ruta de acceso y el nombre de archivo válidos (incluido el carácter NULO de terminación), en TCHAR.

[out] lpBuffer

Puntero al búfer para recibir la ruta de acceso y el nombre de archivo del archivo encontrado. La cadena es una cadena terminada en null.

[out, optional] lpFilePart

Puntero a la variable para recibir la dirección (dentro de lpBuffer) del último componente de la ruta de acceso y el nombre de archivo válidos, que es la dirección del carácter inmediatamente después de la barra diagonal inversa final (\) en la ruta de acceso.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es la longitud, en TCHAR, de la cadena que se copia en el búfer, sin incluir el carácter nulo de terminación. Si el valor devuelto es mayor que nBufferLength, el valor devuelto es el tamaño del búfer necesario para contener la ruta de acceso, incluido el carácter nulo de terminación.

Si la función no se realiza correctamente, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Si el parámetro lpPath es NULL, SearchPath busca un archivo coincidente basado en el valor actual del siguiente valor del Registro:

HKEY_LOCAL_MACHINE\SISTEMA\Currentcontrolset\Control\Administrador de\ sesionesSafeProcessSearchMode

Cuando el valor de este REG_DWORD valor del Registro se establece en 1, SearchPath busca primero las carpetas especificadas en la ruta de acceso del sistema y, a continuación, busca en la carpeta de trabajo actual. Cuando el valor de este valor del Registro se establece en 0, el equipo busca primero en la carpeta de trabajo actual y, a continuación, busca en las carpetas especificadas en la ruta de acceso del sistema. El valor predeterminado del sistema para esta clave del Registro es 0.

El modo de búsqueda que usa la función SearchPath también se puede establecer por proceso mediante una llamada a la función SetSearchPathMode .

La función SearchPath no se recomienda como método para buscar un archivo .dll si el uso previsto de la salida está en una llamada a la función LoadLibrary . Esto puede dar lugar a la búsqueda del archivo de .dll incorrecto porque el orden de búsqueda de la función SearchPath difiere del orden de búsqueda usado por la función LoadLibrary . Si necesita buscar y cargar un archivo .dll, use la función LoadLibrary .

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

Requisitos

Vea también

Funciones de administración de archivos

FindFirstFile

FindNextFile

GetSystemDirectory

GetWindowsDirectory

SetSearchPathMode