LoadLibraryW-Funktion (libloaderapi.h)

Artikel
11/20/2024

Lädt das angegebene Modul in den Adressraum des aufrufenden Prozesses. Das angegebene Modul kann dazu führen, dass andere Module geladen werden.

Verwenden Sie für zusätzliche Ladeoptionen die LoadLibraryEx--Funktion.

Syntax

HMODULE LoadLibraryW(
  [in] LPCWSTR lpLibFileName
);

Parameter

[in] lpLibFileName

Der Name des Moduls. Dies kann ein Bibliotheksmodul (eine .dll Datei) oder ein ausführbares Modul (eine .exe Datei) sein. Wenn es sich bei dem angegebenen Modul um ein ausführbares Modul handelt, werden statische Importe nicht geladen; Stattdessen wird das Modul geladen, als ob LoadLibraryEx mit dem DONT_RESOLVE_DLL_REFERENCES-Flag.

Der angegebene Name ist der Dateiname des Moduls und ist nicht mit dem Namen verknüpft, der im Bibliotheksmodul selbst gespeichert ist, wie durch das schlüsselwort LIBRARY in der Moduldefinitionsdatei (.def) angegeben.

Wenn die Zeichenfolge einen vollständigen Pfad angibt, durchsucht die Funktion nur diesen Pfad für das Modul.

Wenn die Zeichenfolge einen relativen Pfad oder einen Modulnamen ohne Pfad angibt, verwendet die Funktion eine standardmäßige Suchstrategie, um das Modul zu finden; weitere Informationen finden Sie in den Anmerkungen.

Wenn die Funktion das Modul nicht finden kann, schlägt die Funktion fehl. Achten Sie beim Angeben eines Pfads darauf, dass Umgekehrte Schrägstriche (\) und keine Schrägstriche (/) verwendet werden. Weitere Informationen zu Pfaden finden Sie unter Benennen einer Datei oder eines Verzeichnisses.

Wenn die Zeichenfolge einen Modulnamen ohne Pfad angibt und die Dateinamenerweiterung weggelassen wird, fügt die Funktion die Standardbibliothekserweiterung ".DLL" an den Modulnamen an. Um zu verhindern, dass die Funktion ".DLL" an den Modulnamen anfügen kann, fügen Sie ein nachfolgendes Punktzeichen (.) in die Modulnamenzeichenfolge ein.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ein Handle für das Modul.

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

Bemerkungen

Verwenden Sie die SetErrorMode--Funktion, um Fehlermeldungen zu aktivieren oder zu deaktivieren, die vom Ladeprogramm während der DLL-Ladevorgänge angezeigt werden.

LoadLibrary kann verwendet werden, um ein Bibliotheksmodul in den Adressraum des Prozesses zu laden und ein Handle zurückzugeben, das in GetProcAddress verwendet werden kann, um die Adresse einer DLL-Funktion abzurufen. LoadLibrary- können auch zum Laden anderer ausführbarer Module verwendet werden. Beispielsweise kann die Funktion eine .exe Datei angeben, um ein Handle abzurufen, das in FindResource- oder LoadResource-verwendet werden kann. Verwenden Sie LoadLibrary- jedoch nicht, um eine .exe Datei auszuführen. Verwenden Sie stattdessen die funktion CreateProcess.

Wenn es sich bei dem angegebenen Modul um eine DLL handelt, die noch nicht für den Aufrufvorgang geladen ist, ruft das System die dll-DllMain--Funktion mit dem wert DLL_PROCESS_ATTACH auf. Wenn DllMainTRUEzurückgibt, gibt LoadLibrary ein Handle an das Modul zurück. Wenn DllMainFALSE-zurückgibt, entlädt das System die DLL aus dem Adressraum des Prozesses und LoadLibrary gibt NULL-zurück. Es ist nicht sicher, LoadLibrary von DllMainaufzurufen. Weitere Informationen finden Sie im Abschnitt "Hinweise" in DllMain.

Modulhandles sind nicht global oder vererbbar. Ein Aufruf von LoadLibrary durch einen Prozess erzeugt keinen Handle, den ein anderer Prozess verwenden kann, z. B. beim Aufrufen GetProcAddress. Der andere Prozess muss einen eigenen Aufruf an LoadLibrary- für das Modul vornehmen, bevor GetProcAddressaufgerufen wird.

Wenn lpFileName keinen Pfad enthält und mehrere geladene Module mit demselben Basisnamen und derselben Erweiterung vorhanden sind, gibt die Funktion ein Handle an das Modul zurück, das zuerst geladen wurde.

Wenn im parameter lpFileName keine Dateinamenerweiterung angegeben wird, wird die Standardbibliothekserweiterung .dll angefügt. Die Dateinamenzeichenfolge kann jedoch ein nachfolgendes Punktzeichen (.) enthalten, um anzugeben, dass der Modulname keine Erweiterung hat. Wenn kein Pfad angegeben wird, sucht die Funktion nach geladenen Modulen, deren Basisname dem Basisnamen des zu ladenden Moduls entspricht. Wenn der Name übereinstimmt, wird die Ladevorgang erfolgreich ausgeführt. Andernfalls sucht die Funktion nach der Datei.

Das erste durchsuchte Verzeichnis ist das Verzeichnis, das die Bilddatei enthält, die zum Erstellen des aufrufenden Prozesses verwendet wird (weitere Informationen finden Sie unter der CreateProcess-Funktion). Dadurch können private DLL-Dateien (Dynamic Link Library) gefunden werden, die einem Prozess zugeordnet sind, ohne das installierte Verzeichnis des Prozesses zur PATH-Umgebungsvariable hinzuzufügen. Wenn ein relativer Pfad angegeben wird, wird der gesamte relative Pfad an jedes Token in der DLL-Suchpfadliste angefügt. Um ein Modul aus einem relativen Pfad zu laden, ohne einen anderen Pfad zu durchsuchen, verwenden Sie GetFullPathName-, um einen nichtrelativen Pfad abzurufen und LoadLibrary- mit dem nichtrelativen Pfad aufzurufen. Weitere Informationen zur DLL-Suchreihenfolge finden Sie unter Dynamic-Link Bibliothekssuchreihenfolge.

Der Suchpfad kann mithilfe der funktion SetDllDirectory geändert werden. Diese Lösung wird empfohlen, statt SetCurrentDirectory- zu verwenden oder den vollständigen Pfad zur DLL zu codieren.

Wenn ein Pfad angegeben ist und eine Umleitungsdatei für die Anwendung vorhanden ist, sucht die Funktion im Verzeichnis der Anwendung nach dem Modul. Wenn das Modul im Verzeichnis der Anwendung vorhanden ist, ignoriert LoadLibrary den angegebenen Pfad ignoriert und das Modul aus dem Verzeichnis der Anwendung lädt. Wenn das Modul nicht im Verzeichnis der Anwendung vorhanden ist, lädt LoadLibrary das Modul aus dem angegebenen Verzeichnis. Weitere Informationen finden Sie unter Dynamic Link Library Redirection.

Wenn Sie LoadLibrary mit dem Namen einer Assembly ohne Pfadspezifikation aufrufen und die Assembly im systemkompatiblen Manifest aufgeführt wird, wird der Aufruf automatisch an die parallele Assembly umgeleitet.

Das System verwaltet eine Prozessverweisanzahl für alle geladenen Module. Das Aufrufen LoadLibrary erhöht die Referenzanzahl. Durch Aufrufen der FreeLibrary oder FreeLibraryAndExitThread--Funktion wird die Verweisanzahl erhöht. Das System entlädt ein Modul, wenn die Referenzanzahl null erreicht oder der Prozess beendet wird (unabhängig von der Referenzanzahl).

Windows Server 2003 und Windows XP: Der Visual C++-Compiler unterstützt eine Syntax, mit der Sie threadlokale Variablen deklarieren können: _declspec(Thread). Wenn Sie diese Syntax in einer DLL verwenden, können Sie die DLL nicht explizit mit LoadLibrary- in Windows-Versionen vor Windows Vista laden. Wenn Die DLL explizit geladen wird, müssen Sie die lokalen Threadspeicherfunktionen anstelle von _declspec(Thread)verwenden. Ein Beispiel finden Sie unter Verwenden des lokalen Threadspeichers in einer Dynamic Link Library.

Sicherheitsmerkungen

Verwenden Sie die SearchPath--Funktion nicht, um einen Pfad zu einer DLL für einen nachfolgenden LoadLibrary Aufruf abzurufen. Die SearchPath--Funktion verwendet eine andere Suchreihenfolge als LoadLibrary- und verwendet keinen abgesicherten Suchmodus, es sei denn, dies wird explizit durch Aufrufen SetSearchPathMode mit BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODEaktiviert. Daher wird SearchPath- wahrscheinlich zuerst das aktuelle Arbeitsverzeichnis des Benutzers nach der angegebenen DLL durchsuchen. Wenn ein Angreifer eine schädliche Version einer DLL in das aktuelle Arbeitsverzeichnis kopiert hat, verweist der von SearchPath abgerufene Pfad auf die schädliche DLL, die LoadLibrary dann lädt.

Machen Sie keine Annahmen über die Betriebssystemversion basierend auf einem LoadLibrary Aufruf, der nach einer DLL sucht. Wenn die Anwendung in einer Umgebung ausgeführt wird, in der die DLL legitim nicht vorhanden ist, aber eine schädliche Version der DLL sich im Suchpfad befindet, kann die schädliche Version der DLL geladen werden. Verwenden Sie stattdessen die empfohlenen Techniken, die unter Abrufen der Systemversionbeschrieben werden.

Beispiele

Ein Beispiel finden Sie unter Using Run-Time Dynamic Linking.

Anmerkung

Der libloaderapi.h-Header definiert LoadLibrary als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante 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-	libloaderapi.h (include Windows.h)
Library	Kernel32.lib
DLL-	Kernel32.dll