Поделиться через


Функция LocalAlloc (winbase.h)

Выделяет указанное количество байтов из кучи.

Примечание Локальные функции имеют большую нагрузку и предоставляют меньше возможностей, чем другие функции управления памятью. Новые приложения должны использовать функции кучи , если в документации не указано, что следует использовать локальную функцию. Дополнительные сведения см. в разделе Глобальные и локальные функции.
 

Синтаксис

DECLSPEC_ALLOCATOR HLOCAL LocalAlloc(
  [in] UINT   uFlags,
  [in] SIZE_T uBytes
);

Параметры

[in] uFlags

Атрибуты выделения памяти. Значение по умолчанию — LMEM_FIXED . Этот параметр может иметь одно или несколько из указанных ниже значений, за исключением несовместимых сочетаний.

Значение Значение
LHND
0x0042
Объединяет LMEM_MOVEABLE и LMEM_ZEROINIT.
LMEM_FIXED
0x0000
Выделяет фиксированную память. Возвращаемое значение является указателем на объект памяти.
LMEM_MOVEABLE
0x0002
Выделяет перемещаемую память. Блоки памяти никогда не перемещаются в физической памяти, но их можно переместить в кучу по умолчанию.

Возвращаемое значение является дескриптором для объекта памяти. Чтобы преобразовать дескриптор в указатель, используйте функцию LocalLock .

Это значение не может быть объединено с LMEM_FIXED.

LMEM_ZEROINIT
0x0040
Инициализирует содержимое памяти до нуля.
LPTR
0x0040
Объединяет LMEM_FIXED и LMEM_ZEROINIT.
NONZEROLHND
То же, что и LMEM_MOVEABLE.
NONZEROLPTR
То же, что и LMEM_FIXED.
 

Следующие значения являются устаревшими, но предоставляются для совместимости с 16-разрядной версией Windows. Они игнорируются.

LMEM_DISCARDABLE
LMEM_NOCOMPACT
LMEM_NODISCARD

[in] uBytes

Количество байтов, которые необходимо выделить. Если этот параметр равен нулю и параметр uFlags указывает LMEM_MOVEABLE, функция возвращает дескриптор объекту памяти, который помечен как отброшенный.

Возвращаемое значение

Если функция выполняется успешно, возвращаемое значение является дескриптором для вновь выделенного объекта памяти.

Если функция завершается сбоем, возвращается значение NULL. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.

Комментарии

Управление памятью Windows не предоставляет отдельную локальную кучу и глобальную кучу. Таким образом, функции LocalAlloc и GlobalAlloc по сути одинаковы.

Флаги movable-memory LHND, LMEM_MOVABLE и NONZEROLHND добавляют ненужные издержки и требуют безопасного использования блокировки. Их следует избегать, если в документации не указано, что они должны использоваться.

Новые приложения должны использовать функции кучи , если в документации не указано, что следует использовать локальную функцию. Например, некоторые функции Windows выделяют память, которую необходимо освободить с помощью LocalFree.

Если куча не содержит достаточно свободного места для выполнения запроса, LocalAlloc возвращает значение NULL. Так как для указания ошибки используется значение NULL , ноль виртуального адреса никогда не выделяется. Поэтому легко обнаружить использование указателя NULL .

Если функция LocalAlloc завершается успешно, она выделяет по крайней мере запрошенную сумму. Если выделенная сумма больше запрошенной суммы, процесс может использовать всю сумму. Чтобы определить фактическое количество выделенных байтов, используйте функцию LocalSize .

Чтобы освободить память, используйте функцию LocalFree . Освобождение памяти, выделенной с помощью LocalAlloc с помощью GlobalFree, небезопасно.

Примеры

В следующем коде показано простое использование LocalAlloc и 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);
}

Требования

Требование Значение
Минимальная версия клиента Windows XP [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2003 [классические приложения | Приложения UWP]
Целевая платформа Windows
Header winbase.h (включая Windows.h)
Библиотека Kernel32.lib
DLL Kernel32.dll

См. также

Глобальные и локальные функции

Функции кучи

LocalFree

LocalLock

LocalReAlloc

LocalSize

Функции управления памятью