LocalAlloc

Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

This function allocates the specified number of bytes from the heap. In the linear Microsoft Windows CE application programming interface (API) environment, there is no difference between the local heap and the global heap.

HLOCAL
LocalAlloc(
UINT
uFlags
,
UINT
uBytes
);

Parameters

uFlags

[in] Specifies how to allocate memory. If zero is specified, the default is the LMEM_FIXED flag. This parameter is one of the flags listed in the following table.

Value	Description
LMEM_FIXED	Allocates fixed memory. The return value is a pointer to the memory object.
LPTR	Combines the LMEM_FIXED and LMEM_ZEROINIT flags.
LMEM_ZEROINIT	Initializes memory contents to zero.

uBytes

[in] Specifies the number of bytes to allocate.

Return Values

A handle to the newly allocated memory object indicates success. NULL indicates failure. To get extended error information, call GetLastError.

Remarks

If the heap does not contain sufficient free space to satisfy the request, LocalAllocreturns 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 this 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 LocalSizefunction.

To free the memory, use the LocalFreefunction.

For Windows CE versions 1.0 and 1.01, the local heap for each process cannot exceed 1 MB. However, a process can create multiple heaps using the HeapCreatefunction and each of these heaps can be up to 1 MB.

For Windows CE versions 1.0 through 2.12, allocating memory approximately 0 to 7 bytes under 192K in size causes the corresponding call to LocalFreeto fail for certain memory blocks in this size range. The return code is ERROR_INVALID_PARAMETER.

Requirements

Runs on	Versions	Defined in	Include	Link to
Windows CE OS	1.0 and later	Winbase.h		Lmem.lib

Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.