SearchPathW 函数（processenv.h）

项目
11/20/2024

搜索指定路径中的指定文件。

语法

DWORD SearchPathW(
  [in, optional]  LPCWSTR lpPath,
  [in]            LPCWSTR lpFileName,
  [in, optional]  LPCWSTR lpExtension,
  [in]            DWORD   nBufferLength,
  [out]           LPWSTR  lpBuffer,
  [out, optional] LPWSTR  *lpFilePart
);

参数

[in, optional] lpPath

要搜索文件的路径。

如果此参数 NULL，则该函数将使用注册表相关的系统搜索路径来搜索匹配的文件。有关详细信息，请参阅“备注”部分。

[in] lpFileName

要搜索的文件的名称。

[in, optional] lpExtension

搜索文件时要添加到文件名中的扩展名。文件扩展名的第一个字符必须是句点（.）。仅当指定的文件名不以扩展名结尾时，才会添加该扩展名。

如果不需要文件扩展名或文件名包含扩展名，则可以将此参数 NULL。

[in] nBufferLength

接收有效路径和文件名（包括终止 null 字符）的缓冲区的大小，TCHAR。

[out] lpBuffer

指向缓冲区的指针，用于接收找到的文件的路径和文件名。字符串是以 null 结尾的字符串。

[out, optional] lpFilePart

指向接收有效路径和文件名的最后一个组件的地址（lpBuffer）的变量的指针，该地址是路径中最后一个反斜杠（\）紧跟在路径中最后一个反斜杠（\）后面的字符的地址。

返回值

如果函数成功，则返回的值是复制到缓冲区的字符串的长度（以 TCHAR为单位，不包括终止 null 字符）。如果返回值大于 nBufferLength，则返回的值是保存路径所需的缓冲区大小，包括终止 null 字符。

如果函数失败，则返回值为零。若要获取扩展的错误信息，请调用 GetLastError。

言论

如果 lpPath 参数 NULL，SearchPath 基于以下注册表值的当前值搜索匹配文件：

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\SafeProcessSearchMode

当此 REG_DWORD 注册表值的值设置为 1 时，SearchPath 先搜索系统路径中指定的文件夹，然后搜索当前工作文件夹。当此注册表值的值设置为 0 时，计算机首先搜索当前工作文件夹，然后搜索系统路径中指定的文件夹。此注册表项的系统默认值为 0。

SearchPath 函数使用的搜索模式也可以通过调用 setSearchPathMode 函数来按进程设置。

如果输出的预期使用是在调用 LoadLibrary 函数，则不建议将 SearchPath 函数用作查找 .dll 文件的方法。这可能会导致查找错误的 .dll 文件，因为 SearchPath 函数的搜索顺序不同于 LoadLibrary 函数使用的搜索顺序。如果需要查找和加载 .dll 文件，请使用 LoadLibrary 函数。

提示从 Windows 10 版本 1607 开始，对于此函数的 unicode 版本（SearchPathW），可以选择加入以删除 MAX_PATH 限制。有关详细信息，请参阅命名文件、路径和命名空间的“最大路径长度限制”部分。

在 Windows 8 和 Windows Server 2012 中，以下技术支持此函数。

科技	支持
服务器消息块（SMB） 3.0 协议	是的
SMB 3.0 透明故障转移（TFO）	是的
具有横向扩展文件共享的 SMB 3.0 （SO）	是的
群集共享卷文件系统（CsvFS）	是的
可复原文件系统（ReFS）	是的

注意

processenv.h 标头将 SearchPath 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。有关详细信息，请参阅函数原型的约定。

要求

要求	价值
最低支持的客户端	Windows XP [仅限桌面应用]
支持的最低服务器	Windows Server 2003 [仅限桌面应用]
目标平台	窗户
标头	processenv.h （包括 Windows.h）
库	Kernel32.lib
DLL	Kernel32.dll