LoadLibraryA-Funktion (libloaderapi.h)

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

Für zusätzliche Ladeoptionen verwenden Sie die LoadLibraryEx-Funktion .

Syntax

HMODULE LoadLibraryA(
  [in] LPCSTR 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 es sich bei dem angegebenen Modul um ein ausführbares Modul handelt, 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 bezieht sich nicht auf den 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 nach dem Modul.

Wenn die Zeichenfolge einen relativen Pfad oder einen Modulnamen ohne Pfad angibt, verwendet die Funktion eine Standardsuchestrategie, 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, 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üge, 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 SetErrorMode-Funktion , um Fehlermeldungen zu aktivieren oder zu deaktivieren, die vom Ladeprogramm während des DLL-Ladevorgangs 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 LoadLibrary jedoch nicht, um eine .exe-Datei auszuführen. Verwenden Sie stattdessen die CreateProcess-Funktion .

Wenn das angegebene Modul eine DLL ist, die nicht bereits für den aufrufenden Prozess geladen wurde, ruft das System die DllMain-Funktion der DLL mit dem DLL_PROCESS_ATTACH-Wert 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 von DllMain aus aufzurufen. 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 von GetProcAddress. Der andere Prozess muss einen eigenen Aufruf von LoadLibrary für das Modul ausführen, bevor GetProcAddress aufgerufen wird.

Wenn lpFileName keinen Pfad enthält und mehrere module mit demselben Basisnamen und derselben Erweiterung geladen sind, 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 nachfolgendes 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 in 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-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 Funktion SetDllDirectory 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 wird 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 und lädt das Modul aus dem Verzeichnis der Anwendung. 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 Pfadspezifikation aufrufen und die Assembly im systemkompatiblen Manifest aufgeführt ist, wird der Aufruf automatisch an die parallele Assembly weitergeleitet.

Das System verwaltet eine Referenzanzahl 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 die Referenzanzahl 0 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 lokale Threadvariablen deklarieren können: _declspec(thread). Wenn Sie diese Syntax in einer DLL verwenden, können Sie die DLL nicht explizit mit LoadLibrary auf Windows-Versionen vor Windows Vista laden. Wenn Ihre 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 schädliche Version einer DLL in das aktuelle Arbeitsverzeichnis kopiert hat, zeigt 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, wird möglicherweise die böswillige Version der DLL geladen. Verwenden Sie stattdessen die empfohlenen Techniken, die unter Abrufen der Systemversion beschrieben werden.

Beispiele

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

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 nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen

   
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ßlich Windows.h)
Bibliothek Kernel32.lib
DLL Kernel32.dll

Siehe auch

DllMain

Dynamic-Link-Bibliotheksfunktionen

Findresource

FreeLibrary

GetProcAddress

GetSystemDirectory

GetWindowsDirectory

LoadLibraryEx

LoadResource

Dynamisches Verknüpfen zur Laufzeit

SetDllDirectory

SetErrorMode