Fonction LocalAlloc (winbase.h)

Article
08/27/2023

Alloue le nombre spécifié d’octets du tas.

Note Les fonctions locales ont une surcharge plus importante et fournissent moins de fonctionnalités que d’autres fonctions de gestion de la mémoire. Les nouvelles applications doivent utiliser les fonctions de tas , sauf si la documentation indique qu’une fonction locale doit être utilisée. Pour plus d’informations, consultez Fonctions globales et locales.

Syntaxe

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

Paramètres

[in] uFlags

Attributs d’allocation de mémoire. La valeur par défaut est la valeur LMEM_FIXED . Ce paramètre peut être une ou plusieurs des valeurs suivantes, à l’exception des combinaisons incompatibles qui sont spécifiquement notées.

Valeur	Signification
LHND 0x0042	Combine LMEM_MOVEABLE et LMEM_ZEROINIT.
LMEM_FIXED 0x0000	Alloue de la mémoire fixe. La valeur de retour est un pointeur vers l’objet mémoire.
LMEM_MOVEABLE 0x0002	Alloue de la mémoire mobile. Les blocs de mémoire ne sont jamais déplacés dans la mémoire physique, mais ils peuvent être déplacés dans le tas par défaut. La valeur de retour est un handle de l’objet mémoire. Pour traduire le handle en pointeur, utilisez la fonction LocalLock . Cette valeur ne peut pas être combinée avec LMEM_FIXED.
LMEM_ZEROINIT 0x0040	Initialise le contenu de la mémoire à zéro.
LPTR 0x0040	Combine LMEM_FIXED et LMEM_ZEROINIT.
NONZEROLHND	Identique à LMEM_MOVEABLE.
NONZEROLPTR	Identique à LMEM_FIXED.

Les valeurs suivantes sont obsolètes, mais sont fournies à des fins de compatibilité avec Windows 16 bits. Ils sont ignorés.

LMEM_DISCARDABLE

LMEM_NOCOMPACT

LMEM_NODISCARD

[in] uBytes

Nombre d'octets à allouer. Si ce paramètre est égal à zéro et que le paramètre uFlags spécifie LMEM_MOVEABLE, la fonction retourne un handle à un objet mémoire marqué comme ignoré.

Valeur retournée

Si la fonction réussit, la valeur de retour est un handle de l’objet mémoire nouvellement alloué.

Si la fonction échoue, la valeur de retour est NULL. Pour obtenir des informations détaillées sur l’erreur, appelez GetLastError.

Remarques

La gestion de la mémoire Windows ne fournit pas de tas local et de tas global distincts. Par conséquent, les fonctions LocalAlloc et GlobalAlloc sont essentiellement les mêmes.

Les indicateurs de mémoire mobile LHND, LMEM_MOVABLE et NONZEROLHND ajoutent une surcharge inutile et nécessitent un verrouillage pour être utilisé en toute sécurité. Elles doivent être évitées, sauf si la documentation indique expressément qu’elles doivent être utilisées.

Les nouvelles applications doivent utiliser les fonctions de tas , sauf si la documentation indique spécifiquement qu’une fonction locale doit être utilisée. Par exemple, certaines fonctions Windows allouent de la mémoire qui doit être libérée avec LocalFree.

Si le tas ne contient pas suffisamment d’espace libre pour répondre à la demande, LocalAlloc retourne NULL. Étant donné que NULL est utilisé pour indiquer une erreur, l’adresse virtuelle zéro n’est jamais allouée. Il est donc facile de détecter l’utilisation d’un pointeur NULL .

Si la fonction LocalAlloc réussit, elle alloue au moins le montant demandé. Si le montant alloué est supérieur au montant demandé, le processus peut utiliser la totalité du montant. Pour déterminer le nombre réel d’octets alloués, utilisez la fonction LocalSize .

Pour libérer la mémoire, utilisez la fonction LocalFree . Il n’est pas sûr de libérer la mémoire allouée avec LocalAlloc à l’aide de GlobalFree.

Exemples

Le code suivant montre une utilisation simple de LocalAlloc et 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);
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau \| applications UWP]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau \| applications UWP]
Plateforme cible	Windows
En-tête	winbase.h (inclure Windows.h)
Bibliothèque	Kernel32.lib
DLL	Kernel32.dll