SearchPathA 函数 (processenv.h)

项目
03/04/2024

在指定路径搜索指定文件。

语法

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

参数

[in, optional] lpPath

要在其中搜索文件的路径。

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

[in] lpFileName

要搜索的文件的名称。

默认情况下，名称限制为MAX_PATH个字符。若要将此限制扩展到 32,767 个宽字符，请在路径前面添加“\？\”。有关详细信息，请参阅命名文件、路径和命名空间。

提示

从 Windows 10 版本 1607 开始，可以选择删除MAX_PATH限制，而无需在前面添加“\\？\”。有关详细信息，请参阅命名文件、路径和命名空间的“最大路径长度限制”部分。

[in, optional] lpExtension

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

如果文件扩展名不是必需的，或者如果文件名包含扩展名，则此参数可以为 NULL。

[in] nBufferLength

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

[out] lpBuffer

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

[out, optional] lpFilePart

指向变量的指针，用于在 lpBuffer) 有效路径和文件名的最后一个组件（即路径中最后一个反斜杠 (\) 之后的字符地址）接收 (地址。

返回值

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

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

注解

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

\ HKEY_LOCAL_MACHINE系统\CurrentControlSet\控制\会话管理器\SafeProcessSearchMode

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

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

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

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

技术	支持
服务器消息块 (SMB) 3.0 协议	是
SMB 3.0 透明故障转移 (TFO)	是
具有横向扩展文件共享的 SMB 3.0 (SO)	是
群集共享卷文件系统 (CSV)	是
弹性文件系统 (ReFS)	是

注意

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

要求

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