SearchPathA 函式 (processenv.h)

發行項
03/01/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) 內 (位址的變數指標，這是路徑中最後一個反斜杠 (\) 後面的字元位址。

傳回值

如果函式成功，則傳回的值是複製到緩衝區之字串的長度，不包括終止 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 通訊協定	Yes
SMB 3.0 透明故障轉移 (TFO)	Yes
具有向外延展檔案共用的SMB 3.0 (SO)	Yes
叢集共用磁碟區文件系統 (CsvFS)	Yes
彈性檔案系統 (ReFS)	Yes

注意

processenv.h 標頭會將 SearchPath 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平台	Windows
標頭	processenv.h (包含 Windows.h)
程式庫	Kernel32.lib
DLL	Kernel32.dll