GlobalFree function (winbase.h)

Article
10/13/2021

Frees the specified global memory object and invalidates its handle.

Note The global functions have greater overhead and provide fewer features than other memory management functions. New applications should use the heap functions unless documentation states that a global function should be used. For more information, see Global and Local Functions.

Syntax

HGLOBAL GlobalFree(
  [in] _Frees_ptr_opt_ HGLOBAL hMem
);

Parameters

[in] hMem

A handle to the global memory object. This handle is returned by either the GlobalAlloc or GlobalReAlloc function. It is not safe to free memory allocated with LocalAlloc.

Return value

If the function succeeds, the return value is NULL.

If the function fails, the return value is equal to a handle to the global memory object. To get extended error information, call GetLastError.

Remarks

If the process examines or modifies the memory after it has been freed, heap corruption may occur or an access violation exception (EXCEPTION_ACCESS_VIOLATION) may be generated.

The GlobalFree function will free a locked memory object. A locked memory object has a lock count greater than zero. The GlobalLock function locks a global memory object and increments the lock count by one. The GlobalUnlock function unlocks it and decrements the lock count by one. To get the lock count of a global memory object, use the GlobalFlags function.

If an application is running under a debug version of the system, GlobalFree will issue a message that tells you that a locked object is being freed. If you are debugging the application, GlobalFree will enter a breakpoint just before freeing a locked object. This allows you to verify the intended behavior, then continue execution.

Examples

For an example, see GlobalAlloc.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2003 [desktop apps \| UWP apps]
Target Platform	Windows
Header	winbase.h (include Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll

Share via