nf-winbase-localalloc.md

UID	title	description	helpviewer_keywords	old-location	tech.root	ms.assetid	ms.date	ms.keywords	req.header	req.include-header	req.target-type	req.target-min-winverclnt	req.target-min-winversvr	req.kmdf-ver	req.umdf-ver	req.ddi-compliance	req.unicode-ansi	req.idl	req.max-support	req.namespace	req.assembly	req.type-library	req.lib	req.dll	req.irql	targetos	req.typenames	req.redist	ms.custom	f1_keywords	dev_langs	topic_type	api_type	api_location	api_name
NF:winbase.LocalAlloc	LocalAlloc function (winbase.h)	Allocates the specified number of bytes from the heap. (LocalAlloc)	LHND LMEM_FIXED LMEM_MOVEABLE LMEM_ZEROINIT LPTR LocalAlloc LocalAlloc function NONZEROLHND NONZEROLPTR _win32_localalloc base.localalloc winbase/LocalAlloc	base\localalloc.htm	base	da8cd2be-ff4c-4da5-813c-8759a58228c9	12/05/2018	LHND, LMEM_FIXED, LMEM_MOVEABLE, LMEM_ZEROINIT, LPTR, LocalAlloc, LocalAlloc function, NONZEROLHND, NONZEROLPTR, _win32_localalloc, base.localalloc, winbase/LocalAlloc	winbase.h	Windows.h	Windows	Windows XP [desktop apps \| UWP apps]	Windows Server 2003 [desktop apps \| UWP apps]										Kernel32.lib	Kernel32.dll		Windows			19H1	LocalAlloc winbase/LocalAlloc	c++	APIRef kbSyntax	DllExport	Kernel32.dll API-MS-Win-Core-Heap-Obsolete-l1-1-0.dll kernel32legacy.dll API-MS-Win-DownLevel-Kernel32-l2-1-0.dll API-MS-Win-Core-misc-l1-1-0.dll KernelBase.dll MinKernelBase.dll API-Ms-Win-Core-Heap-L2-1-0.dll	LocalAlloc

LocalAlloc function

-description

Allocates the specified number of bytes from the heap.

Note  The local 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 local function should be used. For more information, see Global and Local Functions.

 

-parameters

-param uFlags [in]

The memory allocation attributes. The default is the LMEM_FIXED value. This parameter can be one or more of the following values, except for the incompatible combinations that are specifically noted.

Value	Meaning
LHND 0x0042	Combines LMEM_MOVEABLE and LMEM_ZEROINIT.
LMEM_FIXED 0x0000	Allocates fixed memory. The return value is a pointer to the memory object.
LMEM_MOVEABLE 0x0002	Allocates movable memory. Memory blocks are never moved in physical memory, but they can be moved within the default heap. The return value is a handle to the memory object. To translate the handle to a pointer, use the LocalLock function. This value cannot be combined with LMEM_FIXED.
LMEM_ZEROINIT 0x0040	Initializes memory contents to zero.
LPTR 0x0040	Combines LMEM_FIXED and LMEM_ZEROINIT.
NONZEROLHND	Same as LMEM_MOVEABLE.
NONZEROLPTR	Same as LMEM_FIXED.

 

The following values are obsolete, but are provided for compatibility with 16-bit Windows. They are ignored.

LMEM_DISCARDABLE

LMEM_NOCOMPACT

LMEM_NODISCARD

-param uBytes [in]

The number of bytes to allocate. If this parameter is zero and the uFlags parameter specifies LMEM_MOVEABLE, the function returns a handle to a memory object that is marked as discarded.

-returns

If the function succeeds, the return value is a handle to the newly allocated memory object.

If the function fails, the return value is NULL. To get extended error information, call GetLastError.

-remarks

Windows memory management does not provide a separate local heap and global heap. Therefore, the LocalAlloc and GlobalAlloc functions are essentially the same.

The movable-memory flags LHND, LMEM_MOVABLE, and NONZEROLHND add unnecessary overhead and require locking to be used safely. They should be avoided unless documentation specifically states that they should be used.

New applications should use the heap functions unless the documentation specifically states that a local function should be used. For example, some Windows functions allocate memory that must be freed with LocalFree.

If the heap does not contain sufficient free space to satisfy the request, LocalAlloc returns NULL. Because NULL is used to indicate an error, virtual address zero is never allocated. It is, therefore, easy to detect the use of a NULL pointer.

If the LocalAlloc function succeeds, it allocates at least the amount requested. If the amount allocated is greater than the amount requested, the process can use the entire amount. To determine the actual number of bytes allocated, use the LocalSize function.

To free the memory, use the LocalFree function. It is not safe to free memory allocated with LocalAlloc using GlobalFree.

Examples

The following code shows a simple use of LocalAlloc and LocalFree.

#include <windows.h>
#include <stdio.h>
#include <tchar.h>

void _cdecl _tmain()
{
    LPTSTR pszBuf=NULL;

    pszBuf = (LPTSTR)LocalAlloc(
              LPTR,
              MAX_PATH*sizeof(TCHAR));

    // Handle error condition
    if( pszBuf == NULL )
    {
       _tprintf(TEXT("LocalAlloc failed (%d)\n"), GetLastError());
       return;
    }

    //see how much memory was allocated
    _tprintf(TEXT("LocalAlloc allocated %d bytes\n"), LocalSize(pszBuf));

    // Use the memory allocated

    // Free the memory when finished with it
    LocalFree(pszBuf);
}

-see-also

Global and Local Functions

Heap Functions

LocalFree

LocalLock

LocalReAlloc

LocalSize

Memory Management Functions