Fonction LoadLibraryW (libloaderapi.h)

Article
02/28/2024

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 charge supplémentaires, utilisez la fonction LoadLibraryEx.

Syntaxe

HMODULE LoadLibraryW(
  [in] LPCWSTR 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 (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 de 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 trouver le module ; pour plus d’informations, consultez les remarques.

Si la fonction ne trouve pas le module, la fonction échoue. Lors de la spécification d’un chemin d’accès, veillez à utiliser des barres obliques inverses (\), et non 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 de retour

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’erreur étendues, appelez GetLastError.

Remarques

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 dll DllMain avec la valeur DLL_PROCESS_ATTACH. Si DllMain retourne TRUE, LoadLibrary retourne un handle au module. Si DllMain retourne FAUX, 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 Remarques dans DllMain.

Les handles de module ne sont pas globaux ou héritent. Un appel à LoadLibrary par un processus ne produit pas de handle que d’autres processus peuvent utiliser, par exemple lors de l’appel 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 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, 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, 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 de la liste de 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 rérelatif et appeler loadLibrary avec le chemin d’accès nonrelatif. Pour plus d’informations sur l’ordre de recherche DLL, consultez Dynamic-Link ordre de recherche de bibliothèque.

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 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 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 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, qui loadLibrary chargera ensuite.

N’effectuez 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 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 système.

Exemples

Pour obtenir un exemple, consultez Using Run-Time Dynamic Linking.

Note

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. Le mélange 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	libloaderapi.h (include Windows.h)
bibliothèque	Kernel32.lib
DLL	Kernel32.dll