Fonction LoadLibraryA (libloaderapi.h)

Article
08/24/2023

Charge le module spécifié dans l’espace d’adressage du processus appelant. Le module spécifié peut entraîner le chargement d’autres modules.

Pour obtenir des options de chargement supplémentaires, utilisez la fonction LoadLibraryEx .

Syntaxe

HMODULE LoadLibraryA(
  [in] LPCSTR lpLibFileName
);

Paramètres

[in] lpLibFileName

Nom du module. Il peut s’agir d’un module de bibliothèque (fichier .dll) ou d’un module exécutable (fichier .exe). Si le module spécifié est un module exécutable, les importations statiques ne sont pas chargées ; au lieu de cela, le module est chargé comme si par LoadLibraryEx avec l’indicateur DONT_RESOLVE_DLL_REFERENCES .

Le nom spécifié est le nom de fichier du module et n’est pas lié au nom stocké dans le module de bibliothèque lui-même, tel que spécifié par le mot clé LIBRARY dans le fichier de définition de module (.def).

Si la chaîne spécifie un chemin d’accès complet, la fonction recherche uniquement ce chemin d’accès pour le module.

Si la chaîne spécifie un chemin d’accès relatif ou un nom de module sans chemin d’accès, la fonction utilise une stratégie de recherche standard pour rechercher le module ; Pour plus d’informations, consultez les remarques.

Si la fonction ne trouve pas le module, la fonction échoue. Lorsque vous spécifiez un chemin d’accès, veillez à utiliser des barres obliques inverses (\), et non des barres obliques (/). Pour plus d’informations sur les chemins d’accès, consultez Nommage d’un fichier ou d’un répertoire.

Si la chaîne spécifie un nom de module sans chemin d’accès et que l’extension de nom de fichier est omise, la fonction ajoute l’extension de bibliothèque par défaut « .DLL » au nom du module. Pour empêcher la fonction d’ajouter « .DLL » au nom du module, incluez un caractère de point de fin (.) dans la chaîne de nom du module.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle pour le module.

Si la fonction échoue, la valeur de retour est NULL. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Notes

Pour activer ou désactiver les messages d’erreur affichés par le chargeur pendant les chargements de DLL, utilisez la fonction SetErrorMode .

LoadLibrary peut être utilisé pour charger un module de bibliothèque dans l’espace d’adressage du processus et retourner un handle qui peut être utilisé dans GetProcAddress pour obtenir l’adresse d’une fonction DLL. LoadLibrary peut également être utilisé pour charger d’autres modules exécutables. Par exemple, la fonction peut spécifier un fichier .exe pour obtenir un handle qui peut être utilisé dans FindResource ou LoadResource. Toutefois, n’utilisez pas LoadLibrary pour exécuter un fichier .exe. Utilisez plutôt la fonction CreateProcess .

Si le module spécifié est une DLL qui n’est pas déjà chargée pour le processus appelant, le système appelle la fonction DllMain de la DLL avec la valeur DLL_PROCESS_ATTACH . Si DllMain retourne TRUE, LoadLibrary retourne un handle au module. Si DllMain retourne FALSE, le système décharge la DLL de l’espace d’adressage du processus et LoadLibrary retourne NULL. Il n’est pas sûr d’appeler LoadLibrary à partir de DllMain. Pour plus d’informations, consultez la section Notes dans DllMain.

Les handles de module ne sont pas globaux ou ne peuvent pas être hérités. Un appel à LoadLibrary par un processus ne produit pas de handle qu’un autre processus peut utiliser, par exemple lors de l’appel de GetProcAddress. L’autre processus doit effectuer son propre appel à LoadLibrary pour le module avant d’appeler GetProcAddress.

Si lpFileName n’inclut pas de chemin d’accès et qu’il existe plusieurs modules chargés avec le même nom de base et la même extension, la fonction retourne un handle au module qui a été chargé en premier.

Si aucune extension de nom de fichier n’est spécifiée dans le paramètre lpFileName , l’extension de bibliothèque par défaut .dll est ajoutée. Toutefois, la chaîne de nom de fichier peut inclure un caractère de point de fin (.) pour indiquer que le nom du module n’a pas d’extension. Lorsqu’aucun chemin d’accès n’est spécifié, la fonction recherche les modules chargés dont le nom de base correspond au nom de base du module à charger. Si le nom correspond, le chargement réussit. Sinon, la fonction recherche le fichier.

Le premier répertoire recherché est le répertoire contenant le fichier image utilisé pour créer le processus appelant (pour plus d’informations, consultez la fonction CreateProcess ). Cela permet de trouver des fichiers dll (dynamic-link library) privés associés à un processus sans ajouter le répertoire installé du processus à la variable d’environnement PATH. Si un chemin relatif est spécifié, le chemin d’accès relatif entier est ajouté à chaque jeton dans la liste des chemins de recherche dll. Pour charger un module à partir d’un chemin relatif sans rechercher d’autre chemin, utilisez GetFullPathName pour obtenir un chemin d’accès non relationnel et appelez LoadLibrary avec le chemin d’accès non relationnel. Pour plus d’informations sur l’ordre de recherche des DLL, consultez Ordre de recherche de bibliothèque de liens dynamiques.

Le chemin de recherche peut être modifié à l’aide de la fonction SetDllDirectory . Cette solution est recommandée au lieu d’utiliser SetCurrentDirectory ou de coder en dur le chemin d’accès complet à la DLL.

Si un chemin d’accès est spécifié et qu’il existe un fichier de redirection pour l’application, la fonction recherche le module dans le répertoire de l’application. Si le module existe dans le répertoire de l’application, LoadLibrary ignore le chemin spécifié et charge le module à partir du répertoire de l’application. Si le module n’existe pas dans le répertoire de l’application, LoadLibrary charge le module à partir du répertoire spécifié. Pour plus d’informations, consultez Redirection de bibliothèque de liens dynamiques.

Si vous appelez LoadLibrary avec le nom d’un assembly sans spécification de chemin et que l’assembly est répertorié dans le manifeste compatible système, l’appel est automatiquement redirigé vers l’assembly côte à côte.

Le système gère un nombre de références par processus sur tous les modules chargés. L’appel de LoadLibrary incrémente le nombre de références. L’appel de la fonction FreeLibrary ou FreeLibraryAndExitThread décrémente le nombre de références. Le système décharge un module lorsque son nombre de références atteint zéro ou lorsque le processus se termine (quel que soit le nombre de références).

Windows Server 2003 et Windows XP : Le compilateur Visual C++ prend en charge une syntaxe qui vous permet de déclarer des variables locales de thread : _declspec(thread). Si vous utilisez cette syntaxe dans une DLL, vous ne pourrez pas charger la DLL explicitement à l’aide de LoadLibrary sur les versions de Windows antérieures à Windows Vista. Si votre DLL est chargée explicitement, vous devez utiliser les fonctions de stockage local de thread au lieu de _declspec(thread). Pour obtenir un exemple, consultez Utilisation du stockage local de threads dans une bibliothèque de liens dynamiques.

Remarques sur la sécurité

N’utilisez pas la fonction SearchPath pour récupérer un chemin d’accès à une DLL pour un appel LoadLibrary suivant. La fonction SearchPath utilise un ordre de recherche différent de celui de LoadLibrary et n’utilise pas le mode de recherche de processus sécurisé, sauf si cela est explicitement activé en appelant SetSearchPathMode avec BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE. Par conséquent, SearchPath est susceptible de rechercher d’abord la DLL spécifiée dans le répertoire de travail actuel de l’utilisateur. Si un attaquant a copié une version malveillante d’une DLL dans le répertoire de travail actuel, le chemin récupéré par SearchPath pointe vers la DLL malveillante, que LoadLibrary chargera ensuite.

N’effectuez pas d’hypothèses sur la version du système d’exploitation basée sur un appel LoadLibrary qui recherche une DLL. Si l’application s’exécute dans un environnement où la DLL n’est légitimement pas présente, mais qu’une version malveillante de la DLL se trouve dans le chemin de recherche, la version malveillante de la DLL peut être chargée. Utilisez plutôt les techniques recommandées décrites dans Obtention de la version du système.

Exemples

Pour obtenir un exemple, consultez Utilisation de Run-Time liaison dynamique.

Notes

L’en-tête libloaderapi.h définit LoadLibrary en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Spécifications


Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	libloaderapi.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll