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