SearchPathA 関数 (processenv.h)

  • [アーティクル]

指定したパスで指定したファイルを検索します。

構文

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 文字を含むパスを保持するために必要なバッファーのサイズです。

関数が失敗した場合は、0 を返します。 詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

lpPath パラメーターが NULL の場合、SearchPath は次のレジストリ値の現在の値に基づいて一致するファイルを検索します。

Hkey_local_machine\システム\CurrentControlSet\コントロール\セッション マネージャー\SafeProcessSearchMode

この REG_DWORD レジストリ値の値が 1 に設定されている場合、 SearchPath は最初にシステム パスで指定されたフォルダーを検索し、次に現在の作業フォルダーを検索します。 このレジストリ値の値が 0 に設定されている場合、コンピューターは最初に現在の作業フォルダーを検索し、次にシステム パスで指定されているフォルダーを検索します。 このレジストリ キーのシステム既定値は 0 です。

SearchPath 関数で使用される検索モードは、SetSearchPathMode 関数を呼び出すことでプロセスごとに設定することもできます。

出力の意図した用途が LoadLibrary 関数の呼び出しにある場合、SearchPath 関数は、.dll ファイルを検索する方法としてはお勧めしません。 これにより、 SearchPath 関数の検索順序が LoadLibrary 関数で使用される検索順序と異なるため、間違った .dll ファイルが見つからない可能性があります。 .dll ファイルを見つけて読み込む必要がある場合は、 LoadLibrary 関数を使用します。

Windows 8 と Windows Server 2012 では、この関数は、次のテクノロジによってサポートされています。

テクノロジ サポートされています
サーバー メッセージ ブロック (SMB) 3.0 プロトコル はい
SMB 3.0 Transparent Failover (TFO) はい
スケールアウト ファイル共有 (SO) を使う SMB 3.0 はい
クラスターの共有ボリューム ファイル システム (CsvFS) はい
Resilient File System (ReFS) はい
 

注意

processenv.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして SearchPath を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー processenv.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll

関連項目

File Management 関数

FindFirstFile

FindNextFile

GetSystemDirectory

GetWindowsDirectory

SetSearchPathMode