MALLOC(3)

NOM
malloc, free, calloc, realloc, reallocarray - allocate and free dynamic memory

SYNOPSIS
#include <stdlib.h>

void *malloc(size_t size);
void free(void *ptr);
void *calloc(size_t nmemb, size_t size);
void *realloc(void *ptr, size_t size);
void *reallocarray(void *ptr, size_t nmemb, size_t size);

Exigences de macros de test de fonctionnalités pour la glibc (consulter feature_test_macros(7)) :

reallocarray() :
    Depuis la glibc 2.29 :
        _DEFAULT_SOURCE
    Pour la glibc 2.28 et antérieure :
        _GNU_SOURCE

DESCRIPTION
La fonction malloc() alloue size octets, et renvoie un pointeur sur la mémoire allouée. Le contenu de la zone de mémoire n'est pas initialisé. Si size est nulle, malloc renvoie soit NULL ou un unique pointeur qui pourra être passé ultérieurement à free() avec succès.

La fonction free() libère l'espace mémoire pointé par ptr, qui doit avoir été obtenu lors d'un appel antérieur à malloc(), calloc() ou realloc(). Autrement, ou si free(ptr) a déjà été appelé précédemment, le comportement est indéterminé. Si ptr est NULL, aucune opération n'est effectuée.

La fonction calloc() alloue la mémoire nécessaire pour un tableau de nmemb éléments de size octets chacun, et renvoie un pointeur vers la mémoire allouée. Cette zone mémoire est remplie avec des zéros. Si nmemb ou si size est nulle, calloc renvoie alors NULL ou un unique pointeur qui pourra être passé ultérieurement à free() avec succès. Si la multiplication de nmemb et size résulte en un dépassement d'entier, calloc() renverra alors une erreur. En revanche, un dépassement d'entier ne serait pas détecté dans l'appel suivant à malloc(), mais aurait pour conséquence l'allocation d'un bloc mémoire de taille incorrecte :

    malloc(nmemb * size);

La fonction realloc() modifie la taille du bloc de mémoire pointé par ptr à size octets. Le contenu de la mémoire entre la zone de départ et le minimum des nouvelle et ancienne taille n'est pas modifié. Si la nouvelle taille est plus grande que l'ancienne taille, le contenu de la zone de mémoire nouvellement allouée n'est pas initialisé. Si ptr est NULL, l'appel est équivalent à malloc(size), pour toute valeur de size ; si size vaut zéro et que ptr est non NULL, l'appel est alors équivalent à free(ptr). Si ptr n'est pas NULL, il doit avoir été obtenu par un appel antérieur à malloc(), calloc() ou realloc(). Si la zone pointée était déplacée, un appel à free(ptr) est effectué.

La fonction reallocarray() change la taille du bloc mémoire pointé par ptr pour qu'il soit suffisamment grand pour contenir un tableau de nmemb éléments faisant chacun size octets. C'est équivalent à l'appel

    realloc(ptr, nmemb * size);

Cependant, contrairement à cet appel de realloc(), reallocarray() échoue sans danger dans le cas où la multiplication entraînerait un dépassement. Si un tel dépassement se produit, reallocarray() renvoie NULL, fixe errno à ENOMEM et laisse le bloc mémoire originel inchangé.

VALEUR RENVOYÉE
Les fonctions malloc() et calloc() renvoient un pointeur vers la mémoire allouée, qui est correctement alignée pour n'importe quel type interne. Si elles échouent, elles renvoient NULL. NULL peut également être renvoyé par un appel réussi à malloc() avec un argument size égal à zéro, ou par un appel réussi de calloc() avec nmemb ou size égal à zéro.

La fonction free() ne renvoie pas de valeur.

La fonction realloc() renvoie un pointeur sur la mémoire nouvellement allouée, et qui est correctement alignée pour n'importe quel type interne, ou NULL si la requête échoue. Le pointeur renvoyé peut être identique à ptr si la zone mémoire n'est pas déplacée (par exemple s'il y a de la place pour l'étendre à son emplacement) ou peut être différent de ptr si la zone mémoire est déplacée à une nouvelle adresse. Si size vaut zéro, realloc() renvoie NULL ou un pointeur acceptable pour free(). Si realloc() échoue, le bloc mémoire original reste intact ; il n'est ni libéré ni déplacé.

En cas de succès, la fonction reallocarray() renvoie un pointeur sur la mémoire nouvellement allouée. En cas d'échec, NULL est renvoyé et le bloc mémoire originel n'est pas modifié.

ERREURS
calloc(), malloc(), realloc() et reallocarray() peuvent échouer avec l'erreur suivante :

ENOMEM
    Plus de mémoire. Il est possible que l'application ait atteint les limites RLIMIT_AS ou RLIMIT_DATA décrites dans getrlimit(2).

VERSIONS
reallocarray() first appeared in glibc in version 2.26.

ATTRIBUTS
Pour une explication des termes utilisés dans cette section, consulter attributes(7).
Interface | Attribut | Valeur
malloc(), free(), calloc(), realloc() | Sécurité des threads | MT-Safe

CONFORMITÉ
malloc(), free(), calloc(), realloc() : POSIX.1-2001, POSIX.1-2008, C89, C99.

reallocarray() est une extension non standard apparue pour la première fois dans OpenBSD 5.6 et FreeBSD 11.0.

NOTES
Par défaut, Linux suit une stratégie d'allocation optimiste. Cela signifie que lorsque malloc() ne renvoie pas NULL, il n'y a aucune garantie que la mémoire soit véritablement disponible. S'il devait s'avérer que le système manque de mémoire, un ou plusieurs processus seront tués par l'infâme « OOM killer » (gestionnaire de mémoire). Pour plus d'informations, consultez la description de /proc/sys/vm/overcommit_memory et /proc/sys/vm/oom_adj dans proc(5), ainsi que le fichier Documentation/vm/overcommit-accounting des sources du noyau Linux.

En général, malloc() alloue la mémoire depuis le tas, et ajuste la taille du tas en conséquence avec sbrk(2). Lorsque les blocs de mémoire alloués sont plus larges que MMAP_THRESHOLD octets, l'implémentation de la glibc de malloc alloue la mémoire selon une projection anonyme privée avec mmap(2). MMAP_THRESHOLD vaut 128 ko par défaut et il est ajustable avec mallopt(3). Avant Linux 4.7, les allocations réalisées avec mmap(2) n’étaient pas affectées par la limitation de ressource RLIMIT_DATA ; depuis Linux 4.7, cette limite est aussi prise en compte pour les allocations faites avec mmap(2).

Pour éviter les corruptions d'applications multithread, les mutex sont utilisés en interne pour protéger les structures de données de gestion de mémoire utilisées dans ces fonctions. Dans une application multithread où les threads allouent et libèrent la mémoire en même temps, ces mutex risquent d'entrer en conflit. Pour gérer l'allocation de mémoire de façon évolutive dans les applications multithread, la glibc crée des domaines d'allocation mémoire si un conflit de mutex est détecté. Chaque domaine est un grand espace de mémoire qui est alloué en interne par le système (en utilisant brk(2) ou mmap(2)), et géré avec ses propres mutex.

SUSv2 contraint malloc(), calloc() et realloc() à positionner errno à ENOMEM en cas d'échec. La glibc suppose qu'il en est ainsi (et les versions glibc de ces routines le font) ; si vous utilisez une implémentation personnelle de malloc() qui ne positionne pas errno, certaines routines de bibliothèques peuvent échouer sans indiquer de raison dans errno.

Lorsqu'un programme échoue durant un appel à malloc(), calloc(), realloc() ou free(), cela est presque toujours le signe d'une corruption du tas. Cela survient généralement en cas de débordement d'un bloc mémoire alloué, ou en libérant deux fois le même pointeur.

L'implémentation de malloc() est personnalisable à l'aide des variables d'environnement. Pour plus de précisions, consultez mallopt(3).

VOIR AUSSI
valgrind(1), brk(2), mmap(2), alloca(3), malloc_get_state(3), malloc_info(3), malloc_trim(3), malloc_usable_size(3), mallopt(3), mcheck(3), mtrace(3), posix_memalign(3)

Pour des détails sur l'implémentation de la bibliothèque GNU C, consulter https://sourceware.org/glibc/wiki/MallocInternals.

COLOPHON
Cette page fait partie de la publication 5.08 du projet man-pages Linux. Une description du projet et des instructions pour signaler des anomalies et la dernière version de cette page, peuvent être trouvées à l'adresse https://www.kernel.org/doc/man-pages/.

TRADUCTION
La traduction française de cette page de manuel a été créée par Christophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot <david@tilapin.org> et Grégoire Scano <gregoire.scano@malloc.fr> Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE. Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à <debian-l10n-french@lists.debian.org>.