Поделиться через


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

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

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

Синтаксис

HMODULE LoadLibraryW(
  [in] LPCWSTR lpLibFileName
);

Параметры

[in] lpLibFileName

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

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