Função LoadLibraryW (libloaderapi.h)

Artigo
08/24/2023

Carrega o módulo especificado no espaço de endereço do processo de chamada. O módulo especificado pode fazer com que outros módulos sejam carregados.

Para opções de carga adicionais, use a função LoadLibraryEx .

Sintaxe

HMODULE LoadLibraryW(
  [in] LPCWSTR lpLibFileName
);

Parâmetros

[in] lpLibFileName

O nome do módulo. Pode ser um módulo de biblioteca (um arquivo .dll) ou um módulo executável (um arquivo .exe). Se o módulo especificado for um módulo executável, as importações estáticas não serão carregadas; em vez disso, o módulo é carregado como se fosse LoadLibraryEx com o DONT_RESOLVE_DLL_REFERENCES sinalizador .

O nome especificado é o nome do arquivo do módulo e não está relacionado ao nome armazenado no próprio módulo de biblioteca, conforme especificado pelo palavra-chave LIBRARY no arquivo de definição de módulo (.def).

Se a cadeia de caracteres especificar um caminho completo, a função pesquisará apenas esse caminho para o módulo.

Se a cadeia de caracteres especificar um caminho relativo ou um nome de módulo sem um caminho, a função usará uma estratégia de pesquisa padrão para localizar o módulo; para obter mais informações, consulte os Comentários.

Se a função não conseguir localizar o módulo, a função falhará. Ao especificar um caminho, use barras invertidas (\), não barras (/). Para obter mais informações sobre caminhos, consulte Nomeando um arquivo ou diretório.

Se a cadeia de caracteres especificar um nome de módulo sem um caminho e a extensão de nome de arquivo for omitida, a função acrescentará a extensão de biblioteca padrão ".DLL" ao nome do módulo. Para impedir que a função acrescente ".DLL" ao nome do módulo, inclua um caractere de ponto à direita (.) na cadeia de caracteres de nome do módulo.

Retornar valor

Se a função obtiver êxito, o valor retornado será um identificador para o módulo.

Se a função falhar, o valor retornado será NULL. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Para habilitar ou desabilitar mensagens de erro exibidas pelo carregador durante as cargas de DLL, use a função SetErrorMode .

LoadLibrary pode ser usado para carregar um módulo de biblioteca no espaço de endereço do processo e retornar um identificador que pode ser usado em GetProcAddress para obter o endereço de uma função DLL. LoadLibrary também pode ser usado para carregar outros módulos executáveis. Por exemplo, a função pode especificar um arquivo .exe para obter um identificador que pode ser usado em FindResource ou LoadResource. No entanto, não use LoadLibrary para executar um arquivo .exe. Em vez disso, use a função CreateProcess .

Se o módulo especificado for uma DLL que ainda não está carregada para o processo de chamada, o sistema chamará a função DllMain da DLL com o valor DLL_PROCESS_ATTACH . Se DllMain retornar TRUE, LoadLibrary retornará um identificador para o módulo. Se DllMain retornar FALSE, o sistema descarregará a DLL do espaço de endereço do processo e LoadLibrary retornará NULL. Não é seguro chamar LoadLibrary de DllMain. Para obter mais informações, consulte a seção Comentários em DllMain.

Os identificadores de módulo não são globais ou herdáveis. Uma chamada para LoadLibrary por um processo não produz um identificador que outro processo pode usar , por exemplo, ao chamar GetProcAddress. O outro processo deve fazer sua própria chamada para LoadLibrary para o módulo antes de chamar GetProcAddress.

Se lpFileName não incluir um caminho e houver mais de um módulo carregado com o mesmo nome base e extensão, a função retornará um identificador para o módulo que foi carregado primeiro.

Se nenhuma extensão de nome de arquivo for especificada no parâmetro lpFileName , a extensão de biblioteca padrão .dll será acrescentada. No entanto, a cadeia de caracteres de nome de arquivo pode incluir um caractere de ponto à direita (.) para indicar que o nome do módulo não tem extensão. Quando nenhum caminho é especificado, a função pesquisa módulos carregados cujo nome base corresponde ao nome base do módulo a ser carregado. Se o nome corresponder, a carga terá êxito. Caso contrário, a função pesquisa o arquivo.

O primeiro diretório pesquisado é o diretório que contém o arquivo de imagem usado para criar o processo de chamada (para obter mais informações, consulte a função CreateProcess ). Isso permite que arquivos de DLL (biblioteca de vínculo dinâmico) privado associados a um processo sejam encontrados sem adicionar o diretório instalado do processo à variável de ambiente PATH. Se um caminho relativo for especificado, todo o caminho relativo será acrescentado a cada token na lista de caminhos de pesquisa da DLL. Para carregar um módulo de um caminho relativo sem pesquisar nenhum outro caminho, use GetFullPathName para obter um caminho não relacionado e chame LoadLibrary com o caminho não relacional. Para obter mais informações sobre a ordem de pesquisa da DLL, consulte Ordem de pesquisa da biblioteca de vínculo dinâmico.

O caminho de pesquisa pode ser alterado usando a função SetDllDirectory . Essa solução é recomendada em vez de usar SetCurrentDirectory ou codificar o caminho completo para a DLL.

Se um caminho for especificado e houver um arquivo de redirecionamento para o aplicativo, a função pesquisará o módulo no diretório do aplicativo. Se o módulo existir no diretório do aplicativo, LoadLibrary ignorará o caminho especificado e carregará o módulo do diretório do aplicativo. Se o módulo não existir no diretório do aplicativo, LoadLibrary carregará o módulo do diretório especificado. Para obter mais informações, consulte Redirecionamento da Biblioteca de Vínculo Dinâmico.

Se você chamar LoadLibrary com o nome de um assembly sem uma especificação de caminho e o assembly estiver listado no manifesto compatível com o sistema, a chamada será redirecionada automaticamente para o assembly lado a lado.

O sistema mantém uma contagem de referência por processo em todos os módulos carregados. Chamar LoadLibrary incrementa a contagem de referência. Chamar a função FreeLibrary ou FreeLibraryAndExitThread diminui a contagem de referências. O sistema descarrega um módulo quando sua contagem de referência atinge zero ou quando o processo é encerrado (independentemente da contagem de referência).

Windows Server 2003 e Windows XP: O compilador do Visual C++ dá suporte a uma sintaxe que permite declarar variáveis locais de thread: _declspec(thread). Se você usar essa sintaxe em uma DLL, não poderá carregar a DLL explicitamente usando LoadLibrary em versões do Windows antes do Windows Vista. Se a DLL for carregada explicitamente, você deverá usar as funções de armazenamento local do thread em vez de _declspec(thread). Para obter um exemplo, consulte Usando o armazenamento local de thread em uma biblioteca de vínculo dinâmico.

Comentários de segurança

Não use a função SearchPath para recuperar um caminho para uma DLL para uma chamada LoadLibrary subsequente. A função SearchPath usa uma ordem de pesquisa diferente de LoadLibrary e não usa o modo de pesquisa de processo seguro, a menos que isso seja explicitamente habilitado chamando SetSearchPathMode com BASE_SEARCH_PATH_ENABLE_SAFE_SEARCHMODE. Portanto, é provável que o SearchPath pesquise primeiro o diretório de trabalho atual do usuário para a DLL especificada. Se um invasor tiver copiado uma versão mal-intencionada de uma DLL para o diretório de trabalho atual, o caminho recuperado pelo SearchPath apontará para a DLL mal-intencionada, que LoadLibrary carregará.

Não faça suposições sobre a versão do sistema operacional com base em uma chamada LoadLibrary que pesquisa uma DLL. Se o aplicativo estiver em execução em um ambiente em que a DLL não está legitimamente presente, mas uma versão mal-intencionada da DLL estiver no caminho de pesquisa, a versão mal-intencionada da DLL poderá ser carregada. Em vez disso, use as técnicas recomendadas descritas em Obtendo a versão do sistema.

Exemplos

Para obter um exemplo, consulte Usando Run-Time Vinculação Dinâmica.

Observação

O cabeçalho libloaderapi.h define LoadLibrary como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	libloaderapi.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll