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

Статья
08/24/2023

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

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

Синтаксис

HMODULE LoadLibraryA(
  [in] LPCSTR lpLibFileName
);

Параметры

[in] lpLibFileName

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

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

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

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

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

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

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

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

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

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 см. в статье Dynamic-Link Library Search Order.

Путь поиска можно изменить с помощью функции 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 или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования


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