madvise

NOM

BIBLIOTHÈQUE

SYNOPSIS

#include <sys/mman.h>

int madvise(void addr[.length], size_t length, int advice);

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

madvise() :

    Depuis la glibc 2.19 :
        _DEFAULT_SOURCE
    Jusqu'à la glibc 2.19 incluse :
        _BSD_SOURCE

DESCRIPTION

Initialement, l'appel système gérait un ensemble de valeurs de advice « conventionnelles », disponibles aussi sur d'autres implémentations (notez toutefois que madvise() n'est pas spécifié dans POSIX). Par conséquent, un certain nombre de valeurs de advice spécifiques à Linux ont été ajoutées.  

Valeurs de conseil conventionnelles

Le conseil est spécifié par le paramètre advice qui peut être un des suivants :

MADV_NORMAL

Pas de traitement particulier. Il s'agit du comportement par défaut.

MADV_RANDOM

Prévoir des références de page dans un ordre aléatoire. (Ainsi, la lecture anticipée sera moins utile qu'elle ne l'est en général.)

MADV_SEQUENTIAL

Prévoir des références de page dans un ordre séquentiel. (Ainsi, les pages d'une plage donnée peuvent être systématiquement lues par anticipation, et peuvent être libérées rapidement après avoir été accédées.)

MADV_WILLNEED

Prévoir un accès dans un futur proche. (Ainsi, lire quelques pages de façon anticipée peut être une bonne idée.)

MADV_DONTNEED

Ne pas s'attendre à un accès dans un futur proche (quant au temps, l'application est finie avec la plage donnée, pour que le noyau puisse libérer des ressources qui lui sont associées).

Après une opération MADV_DONTNEED réussie, la sémantique de l'accès en mémoire dans la région indiquée est modifiée : les accès suivants des pages réussiront, mais provoqueront un nouveau remplissage de la mémoire soit avec le contenu à jour du fichier transposé sous-jacent (pour les mappages de fichiers partagés, ceux anonymes partagés et les techniques basées sur shmem telles que les segments de mémoire partagée de System V), soit avec les pages remplies de zéros à la demande pour les tableaux privés anonymes.

Remarquez qu'appliquée à des mappages partagés, MADV_DONTNEED pourrait ne pas aboutir à une libération immédiate des pages dans la plage. Le noyau est libre de retarder la libération des pages jusqu'au bon moment. La mémoire résidente (resident set size, ou RSS) du processus appelant sera par contre immédiatement réduite.

MADV_DONTNEED ne peut pas s'appliquer à des pages verrouillées ou à des pages VM_PFNMAP (les pages marquées par l'attribut VM_PFNMAP interne au noyau sont des régions de mémoire spéciales non gérées par le sous-système de mémoire virtuelle. De telles pages sont généralement créées par des pilotes de périphérique transposant les pages dans l'espace utilisateur).

La prise en charge des pages immenses TLB a été ajoutée à Linux 5.18. Les adresses d'un mappage stockées par des pages immenses TLB doivent être alignées sur la taille de la page immense TLB sous-jacente et la taille de la plage est arrondie à un multiple supérieur de la taille de la page immense TLB sous-jacente.

Valeurs de conseil spécifiques à Linux

MADV_REMOVE (depuis Linux 2.6.16)

Libérer jusqu'à une plage donnée de pages et son stockage de repli associé. Cela revient à faire un trou dans la plage d'octets correspondante du stockage de secours (voir fallocate(2)). Les accès suivants à la plage d'adresses indiquée verront des données de valeur zéro.

La plage d'adresses indiquée doit être transposée, partagée et accessible en écriture. Cet attribut ne peut pas être appliqué à des pages verrouillées ou à des pages VM_PFNMAP.

Dans l'implémentation initiale, seul tmpfs(5) prenait en charge MADV_REMOVE ; mais depuis Linux 3.5, tous les systèmes de fichiers qui prennent en charge le mode FALLOC_FL_PUNCH_HOLE de fallocate(2) gèrent également MADV_REMOVE. Les systèmes de fichiers qui ne gèrent pas MADV_REMOVE échouent avec l'erreur EOPNOTSUPP.

La prise en charge du système de fichier de page immense TLB a été ajoutée à Linux 4.3.

MADV_DONTFORK (depuis Linux 2.6.16)

Ne pas rendre les pages de cette plage disponibles à l'enfant après un fork(2). Cela est utile pour empêcher la sémantique de copie à l'écriture de changer l'emplacement physique d'une page si le parent y écrit après un fork(2) (de tels déplacements posent des problèmes si le matériel accède directement à la page (DMA)).

MADV_DOFORK (depuis Linux 2.6.16)

Annuler l'effet de MADV_DONTFORK et restaurer le comportement par défaut, où un mappage est récupéré à l'aide de fork(2).

MADV_HWPOISON (depuis Linux 2.6.32)

Empoisonner les pages dans la plage indiquée par addr et length et traiter les références ultérieures à ces pages comme une corruption de la mémoire matérielle. Cette opération n'est disponible que pour les processus privilégiés (CAP_SYS_ADMIN). À la suite de cette opération, le processus appelant peut recevoir un SIGBUS et la page devenir non affectée.

Cette fonctionnalité est conçue pour tester du code de gestion des erreurs de mémoire ; elle n'est disponible que si le noyau a été configuré avec CONFIG_MEMORY_FAILURE.

MADV_MERGEABLE (depuis Linux 2.6.32)

Activer la fusion des pages identiques par le noyau (Kernel Samepage Merging, ou KSM) pour les pages dans la plage spécifiée par addr et length. Le noyau analyse régulièrement les régions de la mémoire utilisateur qui ont été marquées comme pouvant être fusionnées, à la recherche de pages avec un contenu identique. Elles sont remplacées par une page unique protégée en écriture (qui sera automatiquement recopiée si un processus veut plus tard modifier le contenu de la page). KSM ne fusionne que les pages anonymes privées (consultez mmap(2)).

La fonctionnalité KSM est prévue pour des applications qui génèrent de nombreuses instances avec les mêmes données (comme les systèmes de virtualisation tels que KVM). Cela consomme beaucoup de puissance de calcul ; utilisez-la prudemment. Voir le fichier Documentation/admin-guide/mm/ksm.rst des sources du noyau Linux pour plus de détails.

Les opérations MADV_MERGEABLE et MADV_UNMERGEABLE ne sont disponibles que si le noyau a été configuré avec CONFIG_KSM.

MADV_UNMERGEABLE (depuis Linux 2.6.32)

Annuler l'effet d'une opération MADV_MERGEABLE précédente sur la plage d'adresses spécifiée ; KSM annule la fusion sur les pages qui avaient été fusionnées dans la plage spécifiée par addr et length.

MADV_SOFT_OFFLINE (depuis Linux 2.6.33)

Déconnecter en douceur les pages dans la plage spécifiée par addr et length. La mémoire de chaque page dans la plage spécifiée est préservée (lors du prochain accès, le même contenu sera visible, mais dans une nouvelle page physique), et la page originale est déconnectée (ce qui signifie qu'elle n'est plus utilisée, et plus prise en compte par les mécanismes habituels de gestion de la mémoire). L'effet de l'opération MADV_SOFT_OFFLINE est invisible au processus appelant (c'est-à-dire qu'elle n'en change pas la sémantique).

Cette fonctionnalité est conçue pour tester du code de gestion des erreurs de mémoire ; elle n'est disponible que si le noyau a été configuré avec CONFIG_MEMORY_FAILURE.

MADV_HUGEPAGE (depuis Linux 2.6.38)

Activer la gestion transparente des pages immenses (Transparent Huge Pages, ou THP) pour les pages dans la plage spécifiée par addr et length. Le noyau analysera régulièrement les régions qui ont été marquées comme candidates aux pages immenses pour les remplacer par des pages immenses. Le noyau allouera aussi des pages immenses directement quand la région est naturellement alignée sur la taille de page immense (consultez posix_memalign(2)).

Cette fonctionnalité est d'abord destinée aux applications qui utilisent tout à la fois de grands mappages, beaucoup de données et de grandes régions d'accès à la mémoire (comme les systèmes de virtualisation tels que QEMU). Elle peut facilement consommer beaucoup de mémoire (par exemple un tableau de 2 Mo qui n'accède qu'à un octet dépensera 2 Mo de mémoire et non une page de 4 Ko). Voir le fichier Documentation/admin-guide/mm/transhuge.rst des sources du noyau Linux pour plus de détails.

La plupart des configurations de noyaux classiques fournissent un comportement à la manière de MADV_HUGEPAGE par défaut, et ainsi MADV_HUGEPAGE n'est normalement pas nécessaire. Il est le plus souvent utile pour les systèmes embarqués où un comportement de type MADV_HUGEPAGE peut ne pas être activé par défaut dans le noyau. Sur de tels systèmes, cet attribut peut être utilisé pour activer THP de manière sélective. À chaque fois que MADV_HUGEPAGE est utilisé, il devrait toujours l'être dans des régions de la mémoire où le développeur sait à l'avance que le motif d'accès ne risquera pas d'augmenter l'empreinte de l'application quand les pages immenses transparentes sont actives.

Depuis Linux 5.4, une analyse automatique des zones éligibles et des remplacements par des pages immenses s'effectue sur les pages anonymes et privées (voir mmap(2)), des pages shmem et des pages mises en cache. Pour tous les types de mémoire, la mémoire ne peut être remplacée que par des pages immenses sur des limites alignées sur les pages immenses. Pour la mémoire projetée sur un fichier (y compris tmpfs (voir tmpfs(2)), le mappage doit naturellement être aussi aligné sur une page immense dans le fichier. De plus, pour les fichiers sauvegardés, la mémoire non tmpfs, le fichier ne doit pas être accessible en écriture et le tableau doit être exécutable.

La VMA ne doit pas avoir de mrquage VM_NOHUGEPAGE, VM_HUGETLB, VM_IO, VM_DONTEXPAND, VM_MIXEDMAP ou VM_PFNMAP, et elle ne peut pas non plus être une mémoire de pile ou une mémoire de secours pour un périphérique où DAX est activé (sauf si ce périphérique est branché à chaud en tant que RAM du système). Le processus ne doit pas avoir de PR_SET_THP_DISABLE positionné (voir prctl(2)).

Les opérations MADV_HUGEPAGE, MADV_NOHUGEPAGE et MADV_COLLAPSE ne sont disponibles que si le noyau a été configuré avec CONFIG_TRANSPARENT_HUGEPAGE et la mémoire pour les fichiers/shmem est seulement prise en charge que si le noyau a été configuré avec CONFIG_READ_ONLY_THP_FOR_FS.

MADV_NOHUGEPAGE (depuis Linux 2.6.38)

S'assurer que la mémoire dans la plage spécifiée par addr et length ne sera pas gérée dans des pages immenses transparentes.

MADV_COLLAPSE (depuis Linux 6.1)

Effectuer une suppression synchronisée autant que possible avec les pages natives projetées par la plage de mémoire en Transparent Huge Pages (THP). MADV_COLLAPSE agit sur l'état actuel de la mémoire du processus appelant et ne fait aucun changement permanent ou ne garantit rien sur la manière dont les pages seront projetées, construites ou défaillantes dans le futur.

/MADV_COLLAPSE gère les pages anonymes privées (voir mmap(2)), les pages shmem et les pages mises en cache. Voir MADV_HUGEPAGE pour des informations générales sur les exigences de mémoire de THP. Si la plage fournie couvre plusieurs VMA, la sémantique de la suppression dans chaque VMA est indépendante des autres. Si la suppression d'une région dimensionnée ou alignée sur une page immense donnée échoue, l'opération peut continuer à essayer de supprimer le reste de la mémoire indiquée. MADV_COLLAPSE alignera automatiquement la plage fournie sur la page immense.

Toutes les pages non résidentes faisant partie de la plage seront d'abord échangées ou mises en erreur, avant d'être copiées sur une page immense fraîchement allouée. Si les pages natives représentent la même page immense projetée en PTE et si elles sont alignées correctement, l'allocation d'une nouvelle page immense peut être évitée et la suppression peut se faire directement. Les pages non projetées verront leurs données initialisées directement à 0 dans la nouvelle page immense. Toutefois, pour chaque région éligible dimensionnée/alignée sur une page immense à supprimer, au moins une page doit être récupérée par la mémoire physique.

MADV_COLLAPSE est indépendant du paramétrage du sysfs (voir sysfs(5)) dans /sys/kernel/mm/transparent_hugepage, tant pour déterminer l'éligibilité THP que la sémantique d'allocation. Voir le fichier Documentation/admin-guide/mm/transhuge.rst des sources du noyau Linux pour plus d'informations. MADV_COLLAPSE ignore également le montage tmpfs huge= lorsqu'il agit sur des fichiers tmpfs. L'allocation de nouvelles pages immenses peut entamer une libération/compactage directs indépendamment des attributs de la VMA (encore que VM_NOHUGEPAGE est toujours respecté).

Lorsque le système a plusieurs nœuds NUMA, la page immense sera allouée à partir du nœud contenant les pages les plus natives.

Si toutes les régions dimensionnées ou alignées sur la page immense et incluses dans la plage fournie ont été supprimées avec succès ou si les THP ont déjà été projetées PMD, cette opération se terminera avec succès. Remarquez que cela ne garantit rien quant aux autres projections possibles de la mémoire. Si plusieurs zones dimensionnées ou alignées sur une page immense échouent à être supprimées, seul le code d'erreur le plus récent sera positionné dans errno.

MADV_DONTDUMP (depuis Linux 3.4)

Exclure de l'image mémoire (« core dump ») les pages dans la plage indiquée par addr et length. C'est utile pour les applications dont de larges zones de mémoire sont notoirement inutiles dans une image mémoire. L'effet de MADV_DONTDUMP est prioritaire sur le masque de bits configuré à l’aide de /proc/pid/coredump_filter, consultez core(5).

MADV_DODUMP (depuis Linux 3.4)

Annuler l'effet d’un MADV_DONTDUMP antérieur.

MADV_FREE (depuis Linux 4.5)

L'application n'a plus besoin des pages dans la plage indiquée par addr et length. Le noyau peut ainsi libérer ces pages mais cela pourrait être différé jusqu'à une pression de la mémoire. Pour chacune des pages marquées comme libérables mais non encore libérées, l'opération sera annulée si l'appelant écrit dans la page. Après une opération MADV_FREE réussie, toutes les données périmées (c'est-à-dire les pages sales ou non écrites) seront perdues quand le noyau libèrera les pages. Cependant, les écritures suivantes dans les pages de la plage auront lieu et le noyau ne pourra pas libérer ces pages salies, de sorte que l'appelant pourra toujours voir les données qui viennent d'être écrites. S'il n'y a pas d'écriture ultérieure, le noyau peut libérer les pages n'importe quand. Une fois que les pages de la plage ont été libérées, l'appelant verra des pages remplies de zéros à la demande à chaque référence ultérieure aux pages.

L'opération MADV_FREE ne peut s'appliquer qu'à des pages anonymes privées (voir mmap(2)). Avant Linux 4.12, avant de libérer des pages sur un système sans espace d'échange, les pages dans la plage donnée étaient libérées instantanément indépendamment de la pression sur la mémoire.

MADV_WIPEONFORK (depuis Linux 4.14

Afficher le processus enfant avec une mémoire pleine de zéros dans cette plage après un fork(2). Cela est utile quand on réplique (fork) un serveur pour s'assurer que les données sensibles au processus (par exemple les graines PRNG, les codes de chiffrement et ainsi de suite) ne soient pas capturées par les processus enfants.

L'opération MADV_WIPEONFORK ne peut s'appliquer qu'aux pages anonymes privées (voir mmap(2)).

Dans l'enfant créé par fork(2), le paramètre MADV_WIPEONFORK reste en place sur la plage d'adresses indiquée. Ce paramètre est vidé lors d'un execve(2).

MADV_KEEPONFORK (depuis Linux 4.14)

Annuler l'effet d’un MADV_WIPEONFORK antérieur.

MADV_COLD (depuis Linux 5.4)

Désactiver une plage de pages donnée. Cela en fera des cibles de libération plus probables en cas de pression sur la mémoire. Il s'agit d'une opération non destructive. Ce conseil pourrait être ignoré pour certaines pages de la plage s'il n'est pas applicable.

MADV_PAGEOUT (depuis Linux 5.4)

Libérer une plage de pages donnée. Cela est utilisé pour libérer de la mémoire occupée par ces pages. Si une page est anonyme, elle peut être échangée. Si une page est mise en cache et sale, elle sera réécrite dans le stockage de repli. Le conseil pourrait être ignoré pour certaines pages de la plage s'il n'est pas applicable.

MADV_POPULATE_READ (depuis Linux 5.14)

Peupler (prefault) les tables de pages lisibles, mettant en erreur toutes les pages de la plage comme si on la lisait manuellement à partir de chaque page ; par contre éviter l'accès réel en mémoire qui aurait été fait après la gestion des erreurs.

Contrairement à MAP_POPULATE, MADV_POPULATE_READ ne cache pas les erreurs, il peut être appliqué à tout ou partie des mappages existants et il peuplera (prefault) toujours les tables de pages lisibles. Un exemple d'utilisation est de peupler un tableau de fichier, en lisant tout le contenu du fichier à partir du disque ; mais les pages ne seront pas salies, donc il ne faudra pas les réécrire sur le disque lorsqu'on les sortira de la mémoire.

Selon le mappage sous-jacent, projeter la page de zéros partagée, pré-allouer la mémoire ou lire le fichier sous-jacent ; les fichiers contenant des trous pourraient ou pas pré-allouer des blocs. Si le peuplement échoue, aucun signal SIGBUS n'est généré mais une erreur est renvoyée.

Si MADV_POPULATE_READ réussit, tous les tables de pages ont été peuplées (prefaulted) et lisibles une fois. Si MADV_POPULATE_READ échoue, certaines tables de page pourraient avoir été peuplées.

MADV_POPULATE_READ ne peut pas être appliqué aux mappages sans droit de lecture ni projections spéciales, par exemple celles marquées par des drapeaux tels que VM_PFNMAP ou VM_IO, ou à des régions de mémoire secrètes créées par en utilisant memfd_secret(2).

Remarquez qu'avec MADV_POPULATE_READ, le processus peut être tué n'importe quand si le système n'a plus assez de mémoire.

MADV_POPULATE_WRITE (depuis Linux 5.14)

Peupler (prefault) les tables de pages lisibles, mettant en erreur toutes les pages de la plage comme si on écrivait manuellement dans chaque page ; par contre éviter l'accès réel en mémoire qui aurait été fait après la gestion des erreurs.

Contrairement à MAP_POPULATE, MADV_POPULATE_WRITE ne cache pas les erreurs, il peut être appliqué à tout ou partie des mappages existants et il peuplera (prefault) toujours les tables de pages accessibles en écriture. Un exemple d'utilisation est de pré-allouer de la mémoire et d'interrompre toute copie sur écriture.

Selon le mappage sous-jacent, projeter la page de zéros partagée, pré-allouer la mémoire ou lire le fichier sous-jacent ; les fichiers contenant des trous pré-alloueront des blocs. Si le peuplement échoue, aucun signal SIGBUS n'est généré mais une erreur est renvoyée.

Si MADV_POPULATE_WRITE réussit, tous les tables de pages ont été peuplés (prefaulted) et écrits une fois. Si MADV_POPULATE_WRITE échoue, certaines tables de page pourraient avoir été peuplées.

MADV_POPULATE_WRITE ne peut pas être appliqué aux mappages sans droit d'écriture ni projections spéciales, par exemple celles marquées par des drapeaux tels que VM_PFNMAP ou VM_IO, ou à des régions de mémoire secrètes créées par en utilisant memfd_secret(2).

Remarquez qu'avec MADV_POPULATE_WRITE, le processus peut être tué n'importe quand si le système n'a plus assez de mémoire.

VALEUR RENVOYÉE

ERREURS

EACCES

advice est MADV_REMOVE, mais la plage d'adresses indiquée n'est pas un mappage partagé où on peut écrire.

EAGAIN

Une ressource du noyau est temporairement indisponible.

EBADF

La projection existe, mais la zone n'est pas associée à un fichier.

EBUSY

(pour MADV_COLLAPSE) N'a pas pu charger la page immense dans cgroup : la limite du cgroup a été dépassée.

EFAULT

advice vaut MADV_POPULATE_READ ou MADV_POPULATE_WRITE et le peuplement (prefault) des tables de pages a échoué car un SIGBUS aurait généré un accès réel à la mémoire et la raison n'est pas une page empoisonnée d'un HW (lesquelles peuvent être créées, par exemple, en utilisant le drapeau MADV_HWPOISON décrit ailleurs dans cette page).

EINVAL

addr n'est pas aligné sur une page ou length est négatif.

EINVAL

advice n'est pas valable.

EINVAL

advice vaut MADV_COLD ou MADV_PAGEOUT et la plage d'adresses indiquée inclut des pages verrouillées, immenses TLB ou VM_PFNMAP.

EINVAL

advice vaut MADV_DONTNEED ou MADV_REMOVE et la plage d'adresses indiquée inclut des pages verrouillées, immenses TLB ou VM_PFNMAP.

EINVAL

advice vaut MADV_MERGEABLE ou MADV_UNMERGEABLE, mais le noyau n'a pas été configuré avec l'option CONFIG_KSM.

EINVAL

advice vaut MADV_FREE ou MADV_WIPEONFORK mais la plage d'adresses indiquée inclut un fichier, des TLB immenses, MAP_SHARED ou des plages VM_PFNMAP.

EINVAL

advice vaut MADV_POPULATE_READ ou MADV_POPULATE_WRITE, mais la plage d'adresses indiquée inclut des plages aux droits insuffisants ou ayant des mappages spéciaux, par exemple marqués par des drapeaux internes au noyau tels que VM_IO ou VM_PFNMAP, ou bien des régions de mémoire secrètes créées en utilisant memfd_secret(2).

EIO

(pour MADV_WILLNEED) Suivre la consigne de pagination sur cette zone dépasserait la limite maximale de mémoire physique utilisable par le processus.

ENOMEM

(pour MADV_WILLNEED) Mémoire insuffisante ; échec de pagination.

ENOMEM

(pour MADV_COLLAPSE) Mémoire insuffisante, impossible d'allouer des pages immenses.

ENOMEM

Les adresses de la plage spécifiée ne sont pas projetées actuellement, ou n'appartiennent pas à l'espace d'adressage du processus.

ENOMEM

advice vaut MADV_POPULATE_READ ou MADV_POPULATE_WRITE et le peuplement (prefaulting) des tables de pages a échoué du fait d'une mémoire insuffisante.

EPERM

advice vaut MADV_HWPOISON, mais l'appelant n'a pas la capacité CAP_SYS_ADMIN.

EHWPOISON

advice vaut MADV_POPULATE_READ ou MADV_POPULATE_WRITE et le peuplement (prefault) des tables de page a échoué car une page empoisonnée d'un HW (des pages empoisonnées de HW peuvent être créées, par exemple, en utilisant le drapeau MADV_HWPOISON décrit ailleurs dans cette page) a été rencontrée.

VERSIONS

POSIX.1-2001 spécifie posix_madvise(3) avec des constantes POSIX_MADV_NORMAL, POSIX_MADV_RANDOM, POSIX_MADV_SEQUENTIAL, POSIX_MADV_WILLNEED, POSIX_MADV_DONTNEED et ainsi de suite, avec un comportement proche des attributs nommés de la même manière que ceux listés ci-dessus.  

Linux

madvise(0, 0, advice) renverra 0 si advice est pris en charge par le noyau et s'il peut s'appuyer dessus pour sonder la prise en charge.  

STANDARDS

HISTORIQUE

Depuis Linux 3.18, la gestion de cet appel système est optionnelle, dépendant du réglage de l'option de configuration CONFIG_ADVISE_SYSCALLS.  

VOIR AUSSI

TRADUCTION

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 à

Index

NOM

BIBLIOTHÈQUE

SYNOPSIS

DESCRIPTION

Valeurs de conseil conventionnelles

Valeurs de conseil spécifiques à Linux

VALEUR RENVOYÉE

ERREURS

VERSIONS

Linux

STANDARDS

HISTORIQUE

VOIR AUSSI

TRADUCTION