LocalFree

The LocalFree function frees the specified local memory object and invalidates its handle.

Note  The local functions are slower than other memory management functions and do not provide as many features. Therefore, new applications should use the heap functions.

HLOCAL LocalFree(
  HLOCAL hMem   // handle to local memory object
);

Parameters

hMem

[in] Handle to the local memory object. This handle is returned by either the LocalAlloc or LocalReAlloc function.

Return Values

If the function succeeds, the return value is NULL.

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

Remarks

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

If the hMem parameter is NULL, LocalFree ignores the parameter and returns NULL.

The LocalFree function will free a locked memory object. A locked memory object has a lock count greater than zero. The LocalLock function locks a local memory object and increments the lock count by one. The LocalUnlock function unlocks it and decrements the lock count by one. To get the lock count of a local memory object, use the LocalFlags function.

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

Requirements

  Windows NT/2000: Requires Windows NT 3.1 or later.
  Windows 95/98: Requires Windows 95 or later.
  Header: Declared in Winbase.h; include Windows.h.
  Library: Use Kernel32.lib.

See Also

Memory Management Overview, Memory Management Functions, GlobalFree, LocalAlloc, LocalFlags, LocalLock, LocalReAlloc, LocalUnlock