FreeLibrary

FreeLibrary is a Windows API function that unloads a dynamically linked library (DLL) from the calling process’s address space. It decrements the DLL’s reference count, which is increased when the DLL is loaded via LoadLibrary or LoadLibraryEx. When the reference count reaches zero, the system unloads the DLL and calls the DLL’s entry-point function with the DLL_PROCESS_DETACH reason.

The function is declared as BOOL FreeLibrary(HMODULE hModule). The hModule parameter must be a handle to a module that was previously loaded by LoadLibrary or LoadLibraryEx and is still loaded in the calling process. A nonzero return value indicates success; zero indicates failure. In the latter case, extended error information can be retrieved with GetLastError.

FreeLibrary’s unloading is subject to reference counting. If other parts of the process still hold references to the DLL, FreeLibrary will not unload it. Conversely, once the final reference is released, the module is unloaded, and the system calls the DLL’s entry point to perform any necessary cleanup. Developers should avoid calling FreeLibrary while inside the DLL’s code during DLL_PROCESS_DETACH, as this can lead to deadlocks or instability.

Common use cases include unloading optional plugins or components at runtime to reduce memory usage or to allow updates without restarting the process. It is important to ensure that no code in the DLL is still executing or holds resources when FreeLibrary is invoked.

See also LoadLibrary, LoadLibraryEx, GetModuleHandle, and GetProcAddress. FreeLibrary is provided by the Windows API and is implemented in Kernel32.dll.