SearchPathW-Funktion (processenv.h)

Artikel
11/20/2024

Sucht nach einer angegebenen Datei in einem angegebenen Pfad.

Syntax

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

Parameter

[in, optional] lpPath

Der Pfad, der nach der Datei gesucht werden soll.

Wenn dieser Parameter NULL-ist, sucht die Funktion mithilfe eines registrierungsabhängigen Systemsuchpfads nach einer übereinstimmenden Datei. Weitere Informationen finden Sie im Abschnitt "Hinweise".

[in] lpFileName

Der Name der Datei, nach der gesucht werden soll.

[in, optional] lpExtension

Die Erweiterung, die dem Dateinamen hinzugefügt werden soll, wenn Sie nach der Datei suchen. Das erste Zeichen der Dateinamenerweiterung muss ein Punkt (.) sein. Die Erweiterung wird nur hinzugefügt, wenn der angegebene Dateiname nicht mit einer Erweiterung endet.

Wenn keine Dateinamenerweiterung erforderlich ist oder der Dateiname eine Erweiterung enthält, kann dieser Parameter NULL-werden.

[in] nBufferLength

Die Größe des Puffers, der den gültigen Pfad und Dateinamen (einschließlich des endenden NULL-Zeichens) empfängt, in TCHARs.

[out] lpBuffer

Ein Zeiger auf den Puffer, um den Pfad und dateinamen der gefundenen Datei zu empfangen. Die Zeichenfolge ist eine mit Null beendete Zeichenfolge.

[out, optional] lpFilePart

Ein Zeiger auf die Variable, um die Adresse (innerhalb lpBuffer) der letzten Komponente des gültigen Pfads und Dateinamens zu empfangen, die die Adresse des Zeichens unmittelbar nach dem endgültigen umgekehrten Schrägstrich (\) im Pfad darstellt.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der zurückgegebene Wert die Länge in TCHARsder Zeichenfolge, die in den Puffer kopiert wird, nicht einschließlich des endenden Nullzeichens. Wenn der Rückgabewert größer als nBufferLengthist, ist der zurückgegebene Wert die Größe des Puffers, der zum Speichern des Pfads erforderlich ist, einschließlich des endenden NULL-Zeichens.

Wenn die Funktion fehlschlägt, ist der Rückgabewert null. Rufen Sie GetLastErrorauf, um erweiterte Fehlerinformationen zu erhalten.

Bemerkungen

Wenn der parameter lpPathNULList, sucht SearchPath basierend auf dem aktuellen Wert des folgenden Registrierungswerts nach einer übereinstimmenden Datei:

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

Wenn der Wert dieses REG_DWORD Registrierungswerts auf 1 festgelegt ist, durchsucht SearchPath zuerst die Ordner, die im Systempfad angegeben sind, und durchsucht dann den aktuellen Arbeitsordner. Wenn der Wert dieses Registrierungswerts auf 0 festgelegt ist, durchsucht der Computer zuerst den aktuellen Arbeitsordner und durchsucht dann die Ordner, die im Systempfad angegeben sind. Der Systemstandardwert für diesen Registrierungsschlüssel ist 0.

Der vom SearchPath-Funktion verwendete Suchmodus kann auch pro Prozess festgelegt werden, indem die SetSearchPathMode--Funktion aufgerufen wird.

Die SearchPath--Funktion wird nicht als Methode zum Auffinden einer .dll Datei empfohlen, wenn sich die beabsichtigte Verwendung der Ausgabe in einem Aufruf der LoadLibrary--Funktion befindet. Dies kann dazu führen, dass die falsche .dll Datei gefunden wird, da sich die Suchreihenfolge der SearchPath--Funktion von der Suchreihenfolge unterscheidet, die von der LoadLibrary-Funktion verwendet wird. Wenn Sie eine .dll Datei suchen und laden müssen, verwenden Sie die funktion LoadLibrary.

Tipp Ab Windows 10, Version 1607, für die Unicode-Version dieser Funktion (SearchPathW), können Sie sich anmelden, um die MAX_PATH Einschränkung zu entfernen. Weitere Informationen finden Sie im Abschnitt "Maximale Pfadlängenbeschränkung" Benennungsdateien, Pfade und Namespaces.

In Windows 8 und Windows Server 2012 wird diese Funktion von den folgenden Technologien unterstützt.

Technologie	Abgestützt
Server Message Block (SMB) 3.0-Protokoll	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Skalierungsdateifreigaben (SO)	Ja
Freigegebenes Clustervolumedateisystem (CsvFS)	Ja
Resilient File System (ReFS)	Ja

Anmerkung

Der processenv.h-Header definiert SearchPath als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	processenv.h (include Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll