LocalAlloc (Windows Embedded CE 6.0)

  • Article

1/6/2010

This function allocates the specified number of bytes from the heap.

Syntax

HLOCAL LocalAlloc(
  UINT uFlags,
  UINT uBytes
);

Parameters

  • uFlags
    [in] Allocates memory. If zero is specified, the default is the LMEM_FIXED flag. The following table shows possible values.

    Value Description

    LMEM_FIXED

    Allocates fixed memory. The return value is a pointer to the memory object.

    LMEM_ZEROINIT

    Initializes memory contents to zero.

    LPTR

    Combines the LMEM_FIXED and LMEM_ZEROINIT flags.
  • uBytes
    [in] Number of bytes to allocate.

Return Value

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

Remarks

In the linear Windows Embedded CE API environment, there is no difference between the local heap and the global heap. LocalAlloc is equivalent to HeapAlloc.

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

If this function succeeds, it allocates at least the amount requested; because heap allocation rounds the size of a memory block up to the next 32-byte boundary, the allocated size may be larger than the requested size. If the amount allocated is greater than the amount requested, the process can use the entire amount.

To determine the number of bytes allocated, use the LocalSize function.

To free the memory, use the LocalFree function.

For Windows Embedded 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 HeapCreate function and each heap can be up to 1 MB.

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

Requirements

Header winbase.h
Library coredll.lib
Windows Embedded CE Windows CE 1.0 and later

See Also

Reference

Memory Management Functions
HeapCreate
LocalFree
LocalReAlloc
LocalSize