Fonction LoadLibraryA (libloaderapi.h)

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 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 (un fichier .dll) ou d’un module exécutable (un 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 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, comme 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 trouver 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 (\), pas 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 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 à partir 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 héritants. 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. Quand 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, la charge 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, voir 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 relatif entier est ajouté à chaque jeton de 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 nonrelatif et appeler LoadLibrary avec le chemin d’accès nonrelatif. Pour plus d’informations sur l’ordre de recherche dll, consultez l’ordre de recherche de la 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 complet de 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 d’accès 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 d’accès 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 sera chargée explicitement, vous devez utiliser les fonctions de stockage local du thread au lieu de _declspec(thread). Pour obtenir un exemple, consultez Utilisation du stockage local thread 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 ultérieur. La fonction SearchPath utilise un ordre de recherche différent de LoadLibrary et n’utilise pas le mode de recherche de processus sans échec, sauf si cela est explicitement activé en appelant SetSearchPathMode avec BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE. Par conséquent, SearchPath est susceptible d’effectuer une recherche dans le répertoire de travail actuel de l’utilisateur pour la DLL spécifiée. 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 charge ensuite.

Ne faites pas d’hypothèses sur la version du système d’exploitation en fonction d’un appel LoadLibrary qui recherche une DLL. Si l’application s’exécute dans un environnement où la DLL n’est pas présente légitimement 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 comme 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.

Configuration requise

   
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 (include Windows.h)
Bibliothèque Kernel32.lib
DLL Kernel32.dll

Voir aussi

DllMain

Fonctions de bibliothèque de liens dynamiques

FindResource

FreeLibrary

GetProcAddress

GetSystemDirectory

GetWindowsDirectory

LoadLibraryEx

LoadResource

Liaison dynamique au moment de l’exécution

SetDllDirectory

SetErrorMode