Функция LoadLibraryA (libloaderapi.h)

Загружает указанный модуль в адресное пространство вызывающего процесса. Указанный модуль может привести к загрузке других модулей.

Для дополнительных параметров загрузки используйте функцию LoadLibraryEx .

Синтаксис

HMODULE LoadLibraryA(
  [in] LPCSTR lpLibFileName
);

Параметры

[in] lpLibFileName

Имя модуля. Это может быть модуль библиотеки (файл .dll) или исполняемый модуль (файл .exe). Если указанный модуль является исполняемым, статический импорт не загружается; Вместо этого модуль загружается так, как если бы loadLibraryEx с флагом DONT_RESOLVE_DLL_REFERENCES .

Указанное имя является именем файла модуля и не связано с именем, хранящимся в самом модуле библиотеки, как указано ключевым словом LIBRARY в файле module-definition (DEF).

Если строка задает полный путь, функция ищет только этот путь для модуля.

Если строка указывает относительный путь или имя модуля без пути, функция использует стандартную стратегию поиска для поиска модуля; Дополнительные сведения см. в примечаниях.

Если функция не может найти модуль, функция завершается ошибкой. При указании пути обязательно используйте обратную косую черту (\), а не косую черту (/). Дополнительные сведения о путях см. в статье об именовании файла или каталога.

Если строка указывает имя модуля без пути и расширение имени файла опущено, функция добавляет расширение библиотеки по умолчанию ".DLL" к имени модуля. Чтобы предотвратить добавление функции ".DLL" к имени модуля, добавьте в строку имени модуля символ конечных точек (.).

Возвращаемое значение

Если функция завершается успешно, возвращаемое значение является дескриптором модуля.

Если функция завершается ошибкой, возвращаемое значение равно NULL. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Комментарии

Чтобы включить или отключить сообщения об ошибках, отображаемые загрузчиком во время загрузки библиотеки DLL, используйте функцию SetErrorMode .

LoadLibrary можно использовать для загрузки модуля библиотеки в адресное пространство процесса и возврата дескриптора, который можно использовать в GetProcAddress для получения адреса функции DLL. LoadLibrary также можно использовать для загрузки других исполняемых модулей. Например, функция может указать файл .exe для получения дескриптора, который можно использовать в FindResource или LoadResource. Однако не используйте LoadLibrary для запуска файла .exe. Вместо этого используйте функцию CreateProcess .

Если указанный модуль является библиотекой DLL, которая еще не загружена для вызывающего процесса, система вызывает функцию DLL DllMain со значением DLL_PROCESS_ATTACH . Если DllMain возвращает значение TRUE, LoadLibrary возвращает дескриптор модулю. Если DllMain возвращает значение FALSE, система выгружает библиотеку DLL из адресного пространства процесса, а LoadLibrary возвращает значение NULL. Небезопасно вызывать LoadLibrary из DllMain. Дополнительные сведения см. в разделе "Примечания" в DllMain.

Дескриптора модуля не являются глобальными или наследуемыми. Вызов LoadLibrary одним процессом не создает дескриптор, который может использовать другой процесс, например при вызове GetProcAddress. Другой процесс должен выполнить собственный вызов LoadLibrary для модуля перед вызовом GetProcAddress.

Если lpFileName не содержит путь и имеется несколько загруженных модулей с одинаковым базовым именем и расширением, функция возвращает дескриптор модулю, который был загружен первым.

Если расширение имени файла не указано в параметре lpFileName , расширение библиотеки по умолчанию .dll добавляется. Однако строка имени файла может содержать символ конечных точек (.), указывающий, что имя модуля не имеет расширения. Если путь не указан, функция ищет загруженные модули, базовые имена которых совпадают с базовым именем загружаемого модуля. Если имя совпадает, загрузка завершается успешно. В противном случае функция выполняет поиск файла.

Первый поиск по каталогу — это каталог, содержащий файл изображения, используемый для создания вызывающего процесса (дополнительные сведения см. в описании функции CreateProcess ). Это позволяет найти частные dll-файлы библиотеки динамической компоновки, связанные с процессом, без добавления установленного каталога процесса в переменную среды PATH. Если указан относительный путь, весь относительный путь добавляется к каждому маркеру в списке путей поиска DLL. Чтобы загрузить модуль из относительного пути без поиска по другому пути, используйте GetFullPathName , чтобы получить нерелятивный путь и вызвать LoadLibrary с нерелятивным путем. Дополнительные сведения о порядке поиска библиотек DLL см. в разделе "Порядок поиска библиотеки динамической компоновки".

Путь поиска можно изменить с помощью функции SetDllDirectory . Это решение рекомендуется вместо использования SetCurrentDirectory или жесткого написания полного пути к библиотеке DLL.

Если указан путь и имеется файл перенаправления для приложения, функция выполняет поиск модуля в каталоге приложения. Если модуль существует в каталоге приложения, LoadLibrary игнорирует указанный путь и загружает модуль из каталога приложения. Если модуль не существует в каталоге приложения, LoadLibrary загружает модуль из указанного каталога. Дополнительные сведения см. в разделе "Перенаправление динамической библиотеки ссылок".

При вызове LoadLibrary с именем сборки без спецификации пути и сборка указана в манифесте, совместимом с системой, вызов автоматически перенаправляется в параллельную сборку.

Система поддерживает количество ссылок на каждый процесс во всех загруженных модулях. Вызов LoadLibrary увеличивает число ссылок. Вызов функции FreeLibrary или FreeLibraryAndExitThread уменьшает количество ссылок. Система выгружает модуль, когда его число ссылок достигает нуля или когда процесс завершается (независимо от количества ссылок).

Windows Server 2003 и Windows XP: Компилятор Visual C++ поддерживает синтаксис, позволяющий объявлять локальные переменные потока: _declspec(thread). Если вы используете этот синтаксис в библиотеке DLL, вы не сможете явно загрузить библиотеку DLL с помощью LoadLibrary в версиях Windows до Windows Vista. Если библиотека DLL будет загружена явным образом, вместо _declspec(thread) необходимо использовать функции локального хранилища потока. Пример см. в разделе "Использование локального хранилища потока" в библиотеке динамической компоновки.

Замечания по безопасности

Не используйте функцию SearchPath для получения пути к библиотеке DLL для последующего вызова LoadLibrary . Функция SearchPath использует другой порядок поиска, отличный от LoadLibrary , и не использует режим безопасного поиска процессов, если этот режим не включен явным образом путем вызова SetSearchPathMode с BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE. Таким образом, SearchPath , скорее всего, сначала будет искать текущий рабочий каталог пользователя для указанной библиотеки DLL. Если злоумышленник скопировал вредоносную версию библиотеки DLL в текущий рабочий каталог, путь , полученный SearchPath , будет указывать на вредоносную библиотеку DLL, которая затем загружается LoadLibrary .

Не делайте предположений о версии операционной системы на основе вызова LoadLibrary , выполняющего поиск библиотеки DLL. Если приложение выполняется в среде, где библиотека DLL является законной, но вредоносная версия библиотеки DLL находится в пути поиска, то может быть загружена вредоносная версия библиотеки DLL. Вместо этого используйте рекомендуемые методы, описанные в разделе "Получение системной версии".

Примеры

Пример см. в разделе "Использование Run-Time динамической компоновки".

Примечание

Заголовок libloaderapi.h определяет LoadLibrary как псевдоним, который автоматически выбирает версию функции ANSI или Юникод на основе определения константы препроцессора ЮНИКОДа. Перемешивание использования нейтральную кодировку псевдонима с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или времени выполнения. Дополнительные сведения см. в соглашениях по прототипам функций.

Требования

   
Минимальная версия клиента Windows XP [только классические приложения]
Минимальная версия сервера Windows Server 2003 [только классические приложения]
Целевая платформа Windows
Header libloaderapi.h (включая Windows.h)
Библиотека Kernel32.lib
DLL Kernel32.dll

См. также

DllMain

Функции библиотеки динамической компоновки

FindResource

FreeLibrary

Функция GetProcAddress

GetSystemDirectory

GetWindowsDirectory

LoadLibraryEx

LoadResource

Динамическое связывание во время выполнения

SetDllDirectory

SetErrorMode