Función LocalAlloc (winbase.h)

Artículo
08/27/2023

Asigna el número especificado de bytes del montón.

Nota Las funciones locales tienen mayor sobrecarga y proporcionan menos características que otras funciones de administración de memoria. Las nuevas aplicaciones deben usar las funciones del montón a menos que la documentación indique que se debe usar una función local. Para obtener más información, vea Funciones globales y locales.

Sintaxis

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

Parámetros

[in] uFlags

Atributos de asignación de memoria. El valor predeterminado es el valor de LMEM_FIXED . Este parámetro puede ser uno o varios de los valores siguientes, excepto las combinaciones incompatibles que se indican específicamente.

Valor	Significado
LHND 0x0042	Combina LMEM_MOVEABLE y LMEM_ZEROINIT.
LMEM_FIXED 0x0000	Asigna memoria fija. El valor devuelto es un puntero al objeto de memoria.
LMEM_MOVEABLE 0x0002	Asigna memoria extraíble. Los bloques de memoria nunca se mueven en memoria física, pero se pueden mover dentro del montón predeterminado. El valor devuelto es un identificador para el objeto de memoria. Para traducir el identificador a un puntero, use la función LocalLock . Este valor no se puede combinar con LMEM_FIXED.
LMEM_ZEROINIT 0x0040	Inicializa el contenido de la memoria en cero.
LPTR 0x0040	Combina LMEM_FIXED y LMEM_ZEROINIT.
NONZEROLHND	Igual que LMEM_MOVEABLE.
NONZEROLPTR	Igual que LMEM_FIXED.

Los valores siguientes están obsoletos, pero se proporcionan para la compatibilidad con Windows de 16 bits. Se omiten.

LMEM_DISCARDABLE

LMEM_NOCOMPACT

LMEM_NODISCARD

[in] uBytes

Número de bytes que se van a asignar. Si este parámetro es cero y el parámetro uFlags especifica LMEM_MOVEABLE, la función devuelve un identificador a un objeto de memoria marcado como descartado.

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es un identificador para el objeto de memoria recién asignado.

Si la función no se realiza correctamente, el valor devuelto es NULL. Para obtener información de error extendida, llame a GetLastError.

Comentarios

La administración de memoria de Windows no proporciona un montón local independiente y un montón global. Por lo tanto, las funciones LocalAlloc y GlobalAlloc son esencialmente las mismas.

Las marcas de memoria extraíble LHND, LMEM_MOVABLE y NONZEROLHND agregan sobrecarga innecesaria y requieren que el bloqueo se use de forma segura. Deben evitarse a menos que la documentación indique específicamente que deben usarse.

Las nuevas aplicaciones deben usar las funciones del montón a menos que la documentación indique específicamente que se debe usar una función local. Por ejemplo, algunas funciones de Windows asignan memoria que se deben liberar con LocalFree.

Si el montón no contiene suficiente espacio libre para satisfacer la solicitud, LocalAlloc devuelve NULL. Dado que NULL se usa para indicar un error, nunca se asigna la dirección virtual cero. Por lo tanto, es fácil detectar el uso de un puntero NULL .

Si la función LocalAlloc se realiza correctamente, asigna al menos la cantidad solicitada. Si la cantidad asignada es mayor que la cantidad solicitada, el proceso puede usar toda la cantidad. Para determinar el número real de bytes asignados, use la función LocalSize .

Para liberar la memoria, use la función LocalFree . No es seguro liberar memoria asignada con LocalAlloc mediante GlobalFree.

Ejemplos

En el código siguiente se muestra un uso sencillo de LocalAlloc y 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);
}

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows XP [aplicaciones de escritorio \| aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2003 [aplicaciones de escritorio \| aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	winbase.h (incluya Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll