SearchPathA-Funktion (processenv.h)

Artikel
03/13/2024

Sucht nach der angegebenen Datei im angegebenen Pfad.

Syntax

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

Parameter

[in, optional] lpPath

Der Pfad, in dem 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 mit Hinweisen.

[in] lpFileName

Der Name der zu suchenden Datei.

Standardmäßig ist der Name auf MAX_PATH Zeichen beschränkt. Um diesen Grenzwert auf 32.767 Breitzeichen zu erweitern, stellen Sie dem Pfad "\\?\" voran. Weitere Informationen finden Sie unter Benennen von Dateien, Pfaden und Namespaces.

Tipp

Ab Windows 10 Version 1607 können Sie die MAX_PATH-Einschränkung aufheben, ohne "\\?\" vorab ausstehen zu müssen. Ausführliche Informationen finden Sie im Abschnitt "Maximale Längenbeschränkung für Pfade" unter Benennen von Dateien, Pfaden und Namespaces .

[in, optional] lpExtension

Die Erweiterung, die dem Dateinamen bei der Suche nach der Datei hinzugefügt werden soll. 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 sein.

[in] nBufferLength

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

[out] lpBuffer

Ein Zeiger auf den Puffer, um den Pfad und Dateinamen der gefundenen Datei zu empfangen. Die Zeichenfolge ist eine NULL-endende Zeichenfolge.

[out, optional] lpFilePart

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

Rückgabewert

Wenn die Funktion erfolgreich ist, entspricht der zurückgegebene Wert der Länge in TCHARs der Zeichenfolge, die in den Puffer kopiert wird, ohne das abschließende NULL-Zeichen. Wenn der Rückgabewert größer als nBufferLength ist, entspricht der zurückgegebene Wert der Größe des Puffers, der zum Speichern des Pfads erforderlich ist, einschließlich des abschließenden NULL-Zeichens.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Wenn der lpPath-ParameterNULL ist, sucht SearchPath basierend auf dem aktuellen Wert des folgenden Registrierungswerts nach einer übereinstimmenden Datei:

HKEY_LOCAL_MACHINE\SYSTEM\Currentcontrolset\Steuerung\Sitzungs-Manager\SafeProcessSearchMode

Wenn der Wert dieses REG_DWORD Registrierungswerts auf 1 festgelegt ist, durchsucht SearchPath zunächst 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 zunächst den aktuellen Arbeitsordner und durchsucht dann die ordner, die im Systempfad angegeben sind. Der Systemstandardwert für diesen Registrierungsschlüssel ist 0.

Der von der SearchPath-Funktion verwendete Suchmodus kann auch prozessbezogen festgelegt werden, indem die SetSearchPathMode-Funktion aufgerufen wird.

Die SearchPath-Funktion wird nicht als Methode zum Auffinden einer .dll-Datei empfohlen, wenn die beabsichtigte Verwendung der Ausgabe in einem Aufruf der LoadLibrary-Funktion erfolgt. Dies kann dazu führen, dass die falsche .dll Datei gesucht 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 LoadLibrary-Funktion .

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

Technologie	Unterstützt
SMB 3.0-Protokoll (Server Message Block)	Ja
SMB 3.0 Transparent Failover (TFO)	Ja
SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO)	Ja
Dateisystem mit freigegebenen Clustervolumes (CsvFS)	Ja
Robustes Dateisystem (Resilient File System, ReFS)	Ja

Hinweis

Der header processenv.h 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
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	processenv.h (windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll