LoadLibraryW-Funktion (libloaderapi.h)

Artikel
08/24/2023

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 entweder ein Bibliotheksmodul (eine .dll-Datei) oder ein ausführbares Modul (eine .exe-Datei) sein. Wenn das angegebene Modul ein ausführbares Modul ist, werden statische Importe nicht geladen. Stattdessen wird das Modul von LoadLibraryEx mit dem DONT_RESOLVE_DLL_REFERENCES Flag geladen.

Der angegebene Name ist der Dateiname des Moduls und steht nicht im Zusammenhang mit dem Namen, der im Bibliotheksmodul selbst gespeichert ist, wie vom LIBRARY-Schlüsselwort (keyword) 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 Standard-Suchstrategie, um das Modul zu finden. Weitere Informationen finden Sie in den Hinweisen.

Wenn die Funktion das Modul nicht finden kann, schlägt die Funktion fehl. Achten Sie beim Angeben eines Pfads darauf, umgekehrte Schrägstriche (\) und keine Schrägstriche (/) zu verwenden. 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 bei der Funktion ein Fehler auftritt, ist der Rückgabewert NULL. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Verwenden Sie die Funktion SetErrorMode , um Fehlermeldungen zu aktivieren oder zu deaktivieren, die vom Ladeprogramm beim Laden der DLL 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 kann auch verwendet werden, um andere ausführbare Module zu laden. Die Funktion kann beispielsweise eine .exe-Datei angeben, um ein Handle abzurufen, das in FindResource oder LoadResource verwendet werden kann. Verwenden Sie jedoch LoadLibrary nicht, um eine .exe-Datei auszuführen. Verwenden Sie stattdessen die CreateProcess-Funktion .

Wenn das angegebene Modul eine DLL ist, die noch nicht für den aufrufenden Prozess geladen ist, ruft das System die DllMain-Funktion der DLL mit dem wert DLL_PROCESS_ATTACH auf. Wenn DllMainTRUE zurückgibt, gibt LoadLibrary ein Handle an das Modul zurück. Wenn DllMainFALSE zurückgibt, entlädt das System die DLL aus dem Prozessadressraum, und LoadLibrary gibt NULL zurück. Es ist nicht sicher, LoadLibrary über DllMain aufzurufen. Weitere Informationen finden Sie im Abschnitt Hinweise in DllMain.

Modulhandles sind nicht global oder vererbbar. Ein Aufruf von LoadLibrary durch einen Prozess erzeugt kein Handle, das ein anderer Prozess verwenden kann, z. B. beim Aufrufen von GetProcAddress. Der andere Prozess muss vor dem Aufrufen von GetProcAddress einen eigenen Aufruf von LoadLibrary für das Modul durchführen.

Wenn lpFileName keinen Pfad enthält und mehr als ein geladenes Modul mit demselben Basisnamen und derselben Erweiterung vorhanden ist, gibt die Funktion ein Handle an das Modul zurück, das zuerst geladen wurde.

Wenn im lpFileName-Parameter keine Dateinamenerweiterung angegeben ist, wird die Standardbibliothekserweiterung .dll angefügt. Die Dateinamenzeichenfolge kann jedoch ein nachgestelltes Punktzeichen (.) enthalten, um anzugeben, dass der Modulname keine Erweiterung hat. Wenn kein Pfad angegeben ist, sucht die Funktion nach geladenen Modulen, deren Basisname mit dem Basisnamen des zu ladenden Moduls übereinstimmt. Wenn der Name übereinstimmt, ist das Laden erfolgreich. Andernfalls sucht die Funktion nach der Datei.

Das erste durchsuchte Verzeichnis ist das Verzeichnis, das die Imagedatei enthält, die zum Erstellen des aufrufenden Prozesses verwendet wird (weitere Informationen finden Sie unter 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-Umgebungsvariablen 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 rufen Sie LoadLibrary mit dem nichtrelativen Pfad auf. Weitere Informationen zur DLL-Suchreihenfolge finden Sie unter Suchreihenfolge der Dynamic-Link-Bibliothek.

Der Suchpfad kann mithilfe der SetDllDirectory-Funktion geändert werden. Diese Lösung wird empfohlen, anstatt SetCurrentDirectory zu verwenden oder den vollständigen Pfad zur DLL hart 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 Anwendungsverzeichnis vorhanden ist, ignoriert LoadLibrary den angegebenen Pfad und lädt das Modul aus dem Anwendungsverzeichnis. 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.For more information, see Dynamic Link Library Redirection.

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

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

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 mithilfe von LoadLibrary auf Windows-Versionen vor Windows Vista laden. Wenn Die DLL explizit geladen wird, müssen Sie die lokalen Speicherfunktionen des Threads anstelle von _declspec(Thread) verwenden. Ein Beispiel finden Sie unter Verwenden des lokalen Threadspeichers in einer Dynamic Link-Bibliothek.

Sicherheitsbemerkungen

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 sicheren Prozesssuchmodus, es sei denn, dies wird explizit durch Aufrufen von SetSearchPathMode mit BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE aktiviert. Daher durchsucht SearchPath wahrscheinlich zuerst das aktuelle Arbeitsverzeichnis des Benutzers nach der angegebenen DLL. Wenn ein Angreifer eine böswillige 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, sich aber eine böswillige Version der DLL im Suchpfad befindet, kann die schädliche Version der DLL geladen werden. Verwenden Sie stattdessen die empfohlenen Techniken, die unter Abrufen der Systemversion beschrieben werden.

Beispiele

Ein Beispiel finden Sie unter Verwenden von Run-Time dynamischen Verknüpfungen.

Hinweis

Der libloaderapi.h-Header definiert LoadLibrary 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	libloaderapi.h (Einschließen von Windows.h)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll