Función SearchPathA (processenv.h)

Artículo
11/20/2024

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 que se va a buscar en 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 para el que se va a buscar.

De forma predeterminada, el nombre se limita 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 Archivos de nomenclatura, rutas de acceso y espacios de nombres.

Propina

A partir de Windows 10, versión 1607, puedes optar por quitar la limitación del MAX_PATH sin tener que prepending "\\?\". Consulte la sección "Limitación máxima de longitud de ruta de acceso" de Archivos de nomenclatura, rutas de acceso y espacios de nombres para obtener más información.

[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 se produce un error en la función, el valor devuelto es cero. Para obtener información de error extendida, llame a GetLastError.

Observaciones

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\SYSTEM\CurrentControlSet\Control\Session Manager\SafeProcessSearchMode

Cuando el valor de este REG_DWORD valor del Registro se establece en 1, SearchPath primero busca en las carpetas especificadas en la ruta 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 usado por la función SearchPath de también se puede establecer por proceso llamando a la función setSearchPathMode .

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

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

Tecnología	Soportado
Protocolo bloque de mensajes del servidor (SMB) 3.0	Sí
Conmutación por error transparente (TFO) de SMB 3.0	Sí
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO)	Sí
Sistema de archivos de volumen compartido de clúster (CsvFS)	Sí
Sistema de archivos resistente (ReFS)	Sí

Nota

El encabezado processenv.h define SearchPath como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2003 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	processenv.h (incluya Windows.h)
biblioteca de	Kernel32.lib
DLL de	Kernel32.dll