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

Статья
2023-08-24

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

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

Синтаксис

HMODULE LoadLibraryA(
  [in] LPCSTR lpLibFileName
);

Параметры

[in] lpLibFileName

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

Указанное имя — это имя файла модуля и не связано с именем, хранящимся в самом модуле библиотеки, как указано ключевым словом библиотеки в файле определения модуля (.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 см. в Dynamic-Link порядке поиска библиотеки.

Путь поиска можно изменить с помощью функции 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 SearchPath использует другой порядок поиска, отличный от LoadLibrary, и он не использует режим безопасного поиска процессов, если только это не включено явным образом путем вызова SetSearchPathMode с BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE. Таким образом, SearchPath, скорее всего, сначала выполните поиск текущего рабочего каталога пользователя для указанной библиотеки DLL. Если злоумышленник скопировал вредоносную версию библиотеки DLL в текущий рабочий каталог, путь, полученный SearchPath, будет указывать на вредоносные библиотеки DLL, которые LoadLibrary затем загружаются.

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

Примеры

Пример см. в разделе Using Run-Time Dynamic Linking.

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	libloaderapi.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll