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

Статья
08/27/2023

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

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

Синтаксис

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.

Флаги 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