Função FreeLibrary (libloaderapi.h)

Artigo
08/24/2023

Libera o módulo DLL (biblioteca de vínculo dinâmico) carregado e, se necessário, diminui sua contagem de referência. Quando a contagem de referência atinge zero, o módulo é descarregado do espaço de endereço do processo de chamada e o identificador não é mais válido.

Sintaxe

BOOL FreeLibrary(
  [in] HMODULE hLibModule
);

Parâmetros

[in] hLibModule

Um identificador para o módulo da biblioteca carregada. LoadLibrary, LoadLibraryEx,
A função GetModuleHandle ou GetModuleHandleEx retorna esse identificador.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

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

Comentários

O sistema mantém uma contagem de referência por processo para cada módulo carregado. Um módulo que foi carregado na inicialização do processo devido à vinculação dinâmica de tempo de carga tem uma contagem de referência de um. A contagem de referência para um módulo é incrementada sempre que o módulo é carregado por uma chamada para LoadLibrary. A contagem de referência também é incrementada por uma chamada para LoadLibraryEx , a menos que o módulo esteja sendo carregado pela primeira vez e esteja sendo carregado como um arquivo de dados ou imagem.

A contagem de referência é decrementada sempre que a função FreeLibrary ou FreeLibraryAndExitThread é chamada para o módulo. Quando a contagem de referências de um módulo atinge zero ou o processo é encerrado, o sistema descarrega o módulo do espaço de endereço do processo. Antes de descarregar um módulo de biblioteca, o sistema permite que o módulo desanexe do processo chamando a função DllMain do módulo, se tiver uma, com o valor DLL_PROCESS_DETACH. Isso dá ao módulo de biblioteca a oportunidade de limpo recursos alocados em nome do processo atual. Depois que a função de ponto de entrada é retornada, o módulo de biblioteca é removido do espaço de endereço do processo atual.

Não é seguro chamar FreeLibrary de DllMain. Para obter mais informações, consulte a seção Comentários em DllMain.

Chamar FreeLibrary não afeta outros processos que estão usando o mesmo módulo.

Tenha cuidado ao chamar FreeLibrary com um identificador retornado por GetModuleHandle. A função GetModuleHandle não incrementa a contagem de referência de um módulo, portanto, passar esse identificador para FreeLibrary pode fazer com que um módulo seja descarregado prematuramente.

Um thread que deve descarregar a DLL na qual está em execução e, em seguida, encerrar-se deve chamar FreeLibraryAndExitThread em vez de chamar FreeLibrary e ExitThread separadamente. Caso contrário, uma condição de corrida pode ocorrer. Para obter detalhes, consulte a seção Comentários de FreeLibraryAndExitThread.

Exemplos

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

Requisitos


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