Provided by: manpages-fr-dev_4.19.0-7_all 
NOM
ioctl_userfaultfd - Créer un descripteur de fichier pour gérer les erreurs de pagination
dans l'espace utilisateur
BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)
SYNOPSIS
#include <linux/userfaultfd.h> /* Définition des constantes UFFD* */
#include <sys/ioctl.h>
int ioctl(int fd, int cmd, ...);
DESCRIPTION
Diverses opérations ioctl(2) peuvent être effectuées sur un objet userfaultfd (créé par un
appel à userfaultfd(2)) en utilisant des appels sous la forme :
ioctl(fd, cmd, argp);
Dans ce qui précède, fd est un descripteur de fichier se rapportant à un objet
userfaultfd, cmd étant une des commandes ci-dessous et argp étant un pointeur vers une
structure de données spécifique à cmd.
Les opérations ioctl(2) sont décrites ci-dessous. Celles UFFDIO_API, UFFDIO_REGISTER et
UFFDIO_UNREGISTER sont utilisées pour configurer le comportement de userfaultfd. Ces
opérations permettent à l'appelant de choisir les fonctionnalités qui seront activées et
le type d'événement transmis à l'application. Ces opérations permettent à l'application
appelante de résoudre des événements de problèmes de pages.
UFFDIO_API
(Depuis Linux 4.3). Activer l'opération de userfaultfd et effectuer la poignée de main de
l'API.
Le paramètre argp est un pointeur vers une structure uffdio_api, définie en tant que :
struct uffdio_api {
__u64 api; /* Version de l'API demandée (entrée) */
__u64 features; /* Fonctionnalités demandées (entrée/sortie) */
__u64 ioctls; /* Opérations ioctl() disponibles (sortie) */
};
Le champ api reflète la version de l'API demandée par l'application.
Le noyau vérifie qu'il peut gérer la version de l'API demandée et il positionne les champs
features et ioctls à des masques de bit représentant toutes les fonctions disponibles et
les opérations ioctl(2) génériques disponibles.
Avant Linux 4.11, le champ features doit être initialisé à zéro avant l'appel UFFDIO_API,
et zéro (c'est-à-dire pas de bit de fonctionnalité) est mis dans le champ features par le
noyau à partir du retour de ioctl(2).
À partir de Linux 4.11, le champ features peut être utilisé pour demander si des fonctions
particulières sont prises en charge et pour activer explicitement des fonctionnalités
userfaultfd désactivées par défaut. Le noyau signale toujours toutes les fonctions
disponibles dans le champ features.
Pour activer les fonctionnalités userfaultfd, l'application doit positionner un bit
correspondant à chaque fonction qu'il veut activer dans le champ features. Si le noyau
gère toutes les fonctionnalités demandées, il les activera. Sinon, il mettra zéro dans la
structure uffdio_api renvoyée et il renverra EINVAL.
Les bits fonctionnels suivants peuvent être positionnés :
UFFD_FEATURE_EVENT_FORK (depuis Linux 4.11)
Quand cette fonctionnalité est activée, les objets userfaultfd associés à un
processus parent sont dupliqués dans un processus enfant lors d'un fork(2) et un
événement UFFD_EVENT_FORK est généré sur le moniteur du userfaultfd
UFFD_FEATURE_EVENT_REMAP (depuis Linux 4.11)
Si cette fonctionnalité est activée, quand le processus fautif appelle mremap(2),
le moniteur userfaultfd recevra un événement de type UFFD_EVENT_REMAP.
UFFD_FEATURE_EVENT_REMOVE (depuis Linux 4.11)
Si cette fonctionnalité est ativée, quand le processus fautif appelle madvise(2)
avec les valeurs MADV_DONTNEED ou MADV_REMOVE pour libérer une zone de mémoire
virtuelle, le moniteur userfaultfd recevra un événement de type UFFD_EVENT_REMOVE.
UFFD_FEATURE_EVENT_UNMAP (depuis Linux 4.11)
Si cette fonctionnalité est activée, quand le processus fautif désassocie la
mémoire virtuelle explicitement avec munmap(2), ou implicitement lors d'un mmap(2)
ou d'un mremap(2), le moniteur userfaultfd recevra un événement de type
UFFD_EVENT_UNMAP.
UFFD_FEATURE_MISSING_HUGETLBFS (depuis Linux 4.11)
Si ce bit fonctionnel est positionné, le noyau gère l'enregistrement des plages
userfaultfd par défaut dans les zones hugetlbfs de mémoire virtuelle
UFFD_FEATURE_MISSING_SHMEM (depuis Linux 4.11)
Si ce bit fonctionnel est positionné, le noyau prend en charge l'enregistrement de
plages userfaultfd dans les zones de mémoire partagées. Cela comprend toutes les
APIs de mémoire partagée du noyau : la mémoire partagée System V, tmpfs(5), les
tableaux partagés de /dev/zero, mmap(2) avec l'attribut MAP_SHARED positionné,
memfd_create(2) et ainsi de suite.
UFFD_FEATURE_SIGBUS (depuis Linux 4.14)
Si ce bit fonctionnel est positionné, aucun événement d'erreur de page
(UFFD_EVENT_PAGEFAULT) ne sera généré. Un signal SIGBUS sera plutôt envoyé au
processus fautif. Les applications qui utilisent cette fonctionnalité n'exigeront
pas qu'on utilise un moniteur userfaultfd pour gérer les accès mémoire aux régions
enregistrées avec userfaultfd.
UFFD_FEATURE_THREAD_ID (depuis Linux 4.14)
Si ce bit de fonctionnalité est positionné, uffd_msg.pagefault.feat.ptid sera
positionné sur l'identifiant du thread fautif pour chaque message d'erreur de
pagination.
UFFD_FEATURE_MINOR_HUGETLBFS (depuis Linux 5.13)
Si ce bit fonctionnel est positionné, le noyau gère l'enregistrement des plages
userfaultfd en mode mineur dans les zones hugetlbfs-backed de mémoire.
UFFD_FEATURE_MINOR_SHMEM (depuis Linux 5.14)
Si ce bit fonctionnel est positionné, le noyau gère l'enregistrement des plages
userfaultfd en mode mineur dans les zones shmem-backed de mémoire.
Le champ ioctls renvoyé peut contenir les bits suivants :
1 << _UFFDIO_API
L'opération UFFDIO_API est prise en charge.
1 << _UFFDIO_REGISTER
L'opération UFFDIO_REGISTER est prise en charge.
1 << _UFFDIO_UNREGISTER
L'opération UFFDIO_UNREGISTER est prise en charge.
Cette opération ioctl(2) renvoie 0 en cas de succès. En cas d'erreur, -1 est renvoyé et
errno est positionné pour indiquer l'erreur. Parmi les erreurs possibles :
EFAULT argp renvoie à une adresse en dehors de l'espace d'adressage accessible du
processus appelant.
EINVAL Le userfaultfd a déjà été activé par une précédente opération UFFDIO_API.
EINVAL La version de l'API demandée dans le champ api n'est pas prise en charge par ce
noyau ou le champ features passé au noyau comprend des bits non gérés par la
version actuelle du noyau.
UFFDIO_REGISTER
(Depuis Linux 4.3). Enregistrer une plage d'adresse mémoire avec l'objet userfaultfd. Les
pages de cette plage doivent être « compatibles ». Veuillez vous reporter à la liste des
modes d'enregistrement ci-dessous pour les dorsales de mémoire compatibles avec chaque
mode.
Le paramètre argp est un pointeur vers une structure uffdio_register, définie en tant
que :
struct uffdio_range {
__u64 start; /* Début de la plage */
__u64 len; /* Longueur de la plage (octets) */
};
struct uffdio_register {
struct uffdio_range range;
__u64 mode; /* Mode désiré de l'opération (entrée) */
__u64 ioctls; /* Opérations ioctl() disponibles (sortie) */
};
Le champ range définit une plage de mémoire commençant à start et s'étendant sur len
octets qui doit être gérée par userfaultfd.
Le champ mode définit le mode d'opération désiré pour cette région de mémoire. Les valeurs
suivantes peuvent être mises en bits et liées pour positionner le mode userfaultfd pour la
plage indiquée :
UFFDIO_REGISTER_MODE_MISSING
Suivre les erreurs de pagination sur les pages absentes. Depuis Linux 4.3, seules
les plages anonymes privées sont compatibles. Depuis Linux 4.11, les plages
hugetlbfs et de mémoire partagée sont également compatibles.
UFFDIO_REGISTER_MODE_WP
Suivre les erreurs de pagination sur les pages protégées en écriture. Depuis Linux
5.7, seules les plages anonymes et privées sont compatibles.
UFFDIO_REGISTER_MODE_MINOR
Suivre les petites erreurs de pagination. Depuis Linux 5.13, seules les plages
hugetlbfs sont compatibles. Depuis Linux 5.14, la compatibilité avec les plages
shmem a été ajoutée.
Si l'opération réussit, le noyau modifie le champ du masque de bit ioctls pour indiquer
les opérations ioctl(2) disponibles sur la plage indiquée. Ce masque de bit renvoyé peut
contenir les bits suivants :
1 << _UFFDIO_COPY
L'opération UFFDIO_COPY est prise en charge.
1 << _UFFDIO_WAKE
L'opération UFFDIO_WAKE est prise en charge.
1 << _UFFDIO_WRITEPROTECT
L'opération UFFDIO_WRITEPROTECT
1 << _UFFDIO_ZEROPAGE
L'opération UFFDIO_ZEROPAGE est prise en charge.
1 << _UFFDIO_CONTINUE
L'opération UFFDIO_CONTINUE est prise en charge.
Cette opération ioctl(2) renvoie 0 en cas de succès. En cas d'erreur, -1 est renvoyé et
errno est positionné pour indiquer l'erreur. Parmi les erreurs possibles :
EBUSY Un tableau de la plage indiquée est enregistré avec un autre objet userfaultfd.
EFAULT argp renvoie à une adresse en dehors de l'espace d'adressage accessible du
processus appelant.
EINVAL Un bit non valable ou non pris en charge a été indiqué dans le champ mode ; ou le
champ mode valait zéro.
EINVAL Il n'y a pas de tableau dans la plage d'adresse indiquée.
EINVAL range.start ou range.len n'est pas un multiple de la taille de la page du système ;
ou range.len vaut zéro ; ou ces champs ne sont pas valables pour d'autres raisons.
EINVAL Un tableau incompatible est présent dans la plage d'adresse indiquée.
UFFDIO_UNREGISTER
(Depuis Linux 4.3). Désenregistre une plage d'adresse mémoire de userfaultfd. Les pages de
cette plage doivent être « compatibles » (voir la description de UFFDIO_REGISTER).
La plage d'adresse à désenregistrer est indiquée dans la structure uffdio_range vers
laquelle pointe argp.
Cette opération ioctl(2) renvoie 0 en cas de succès. En cas d'erreur, -1 est renvoyé et
errno est positionné pour indiquer l'erreur. Parmi les erreurs possibles :
EINVAL Le champ start ou len de la structure ufdio_range n'était pas un multiple de la
taille de la page système ; ou bien le champ len valait zéro ; ou ces champs
n'étaient pas valables pour d'autres raisons.
EINVAL Un tableau incompatible est présent dans la plage d'adresse indiquée.
EINVAL Il n'y avait pas de tableau dans la plage d'adresse spécifiée.
UFFDIO_COPY
(Depuis Linux 4.3). Copier de manière atomique un bloc de mémoire continu dans la plage
enregistrée pour le userfault et réveiller éventuellement les threads bloqués. Les
adresses source et cible et le nombre d'octets à copier sont indiqués dans les champs src,
dst et len de la structure uffdio_copy vers laquelle pointe argp :
struct uffdio_copy {
__u64 dst; /* Cible de la copie */
__u64 src; /* Origine de la copie */
__u64 len; /* Nombre d'octets à copier */
__u64 mode; /* Drapeaux contrôlant le comportement de la copie */
__s64 copy; /* Nombre d'octets copiés ou erreurs de refus */
};
La valeur suivante peut être liée en bits à mode pour modifier le comportement de
l'opération UFFDIO_COPY :
UFFDIO_COPY_MODE_DONTWAKE
Ne pas réveiller le thread qui attend la résolution d'une erreur de page
UFFDIO_COPY_MODE_WP
Copier les pages avec des droits en lecture seule. Cela permet à l'utilisateur de
récupérer la prochaine écriture sur la page qui bloquera et qui génèrera un autre
message userfault de protection en écriture. Cela n'est utilisé que lorsque les
modes UFFDIO_REGISTER_MODE_MISSING et UFFDIO_REGISTER_MODE_WP sont activés pour la
plage enregistrée.
Le champ copy est utilisé par le noyau pour renvoyer le nombre d'octets copiés ou une
erreur (une valeur négative à la façon errno). Si la valeur renvoyée dans copy ne
correspond pas à celle indiquée dans len, l'opération échoue avec l'erreur EAGAIN. Le
champ copy n'est fait que pour la sortie ; il n'est pas lu par l'opération UFFDIO_COPY.
Cette opération ioctl(2) renvoie 0 en cas de succès. Dans ce cas, toute la zone a été
copiée. En cas d'erreur, -1 est renvoyé et errno est positionné pour indiquer l'erreur.
Parmi les erreurs possibles :
EAGAIN Le nombre d'octets copiés (à savoir la valeur renvoyée dans le champ copy) n'est
pas la même que celle indiquée dans le champ len.
EINVAL dst ou len n'était pas un multiple de la taille de la page du système ou la plage
indiquée dans src et len ou dst et len n'était pas valable.
EINVAL Un bit non valable a été indiqué dans le champ mode.
ENOENT (depuis Linux 4.11)
Le processus fautif a modifié sa structure de mémoire virtuelle en même temps
qu'une opération UFFDIO_COPY remarquable.
ENOSPC (de Linux 4.11 à Linux 4.13)
Le processus fautif a quitté au moment de l'opération UFFDIO_COPY.
ESRCH (depuis Linux 4.13)
Le processus fautif a quitté au moment de l'opération UFFDIO_COPY.
UFFDIO_ZEROPAGE
(Depuis Linux 4.3). Remplit de zéros une plage mémoire enregistrée avec userfaultfd.
La plage demandée est indiquée par le champ range de la structure uffdio_zeropage vers
laquelle pointe argp :
struct uffdio_zeropage {
struct uffdio_range range;
__u64 mode; /* Drapeaux contrôlant le comportement de la copie */
__s64 zeropage; /* Nombre d'octets remplis de zéros ou d'erreurs de refus */
};
La valeur suivante peut être mise en bit et liée dans mode pour modifier le comportement
de l'opération UFFDIO_ZEROPAGE :
UFFDIO_ZEROPAGE_MODE_DONTWAKE
Ne pas réveiller le thread qui attend la résolution d'une erreur de page.
Le champ zeropage est utilisé par le noyau pour renvoyer le nombre d'octets remplis de
zéros, ou une erreur de la même manière que UFFDIO_COPY. Si la valeur renvoyée dans le
champ zeropage ne correspond pas à celle indiquée dans range.len, l'opération échoue avec
l'erreur EAGAIN. Le champ zeropage ne sert qu'à la sortie ; il n'est pas lu par
l'opération UFFDIO_ZEROPAGE.
L'opération ioctl(2) renvoie 0 en cas de succès. Dans ce cas, toute la zone a été remplie
de zéros. En cas d'erreur, -1 est renvoyé et errno est positionné pour indiquer l'erreur.
Parmi les erreurs possibles :
EAGAIN Le nombre d'octets remplis de zéros (c'est-à-dire la valeur renvoyée dans le champ
zeropage) ne correspond pas à la valeur indiquée dans le champ range.len.
EINVAL range.start ou range.len n'était pas un multiple de la taille de la page du
système ; ou range.len était de zéro ; ou la plage indiquée n'était pas valable.
EINVAL Un bit non valable a été indiqué dans le champ mode.
ESRCH (depuis Linux 4.13)
Le processus fautif a quitté au moment de l'opération UFFDIO_ZEROPAGE.
UFFDIO_WAKE
(Depuis Linux 4.3). Réveiller le thread qui attend la résolution de l'erreur de page sur
une plage d'adresse mémoire indiquée.
L'opération UFFDIO_WAKE est utilisée avec les opérations UFFDIO_COPY et UFFDIO_ZEROPAGE,
dont le bit UFFDIO_COPY_MODE_DONTWAKE ou UFFDIO_ZEROPAGE_MODE_DONTWAKE est défini dan le
champ mode. Le moniteur userfault peut effectuer plusieurs opérations UFFDIO_COPY et
UFFDIO_ZEROPAGE automatiquement, puis réveiller explicitement le thread fautif en
utilisant UFFDIO_WAKE.
Le paramètre argp est un pointeur vers une structure uffdio_range (présentée ci-dessus)
qui indique la plage d'adresse.
Cette opération ioctl(2) renvoie 0 en cas de succès. En cas d'erreur, -1 est renvoyé et
errno est positionné pour indiquer l'erreur. Parmi les erreurs possibles :
EINVAL Le champ start ou len de la structure ufdio_range n'était pas un multiple de la
taille de la page système ; ou len était zéro ; ou la plage indiquée n'était pas
valable pour une autre raison.
UFFDIO_WRITEPROTECT (depuis Linux 5.7)
Verrouiller ou déverrouiller en écriture une plage de mémoire userfaultfd enregistrée avec
les accès UFFDIO_REGISTER_MODE_WP.
Le paramètre argp est un pointeur vers une structure uffdio_range, comme indiqué
ci-dessous :
struct uffdio_writeprotect {
struct uffdio_range range; /* Plage pour modifier le droit d'écriture*/
__u64 mode; /* Mode pour changer le droit d'écriture */
};
Deux bits de droit sont pris en charge dans cette structure :
UFFDIO_WRITEPROTECT_MODE_WP
Quand ce bit de droits est positionné, l'ioctl sera une opération protégée en
écriture sur la plage mémoire indiquée par range. Sinon, il s'agira d'une opération
non protégée en écriture sur la plage indiquée, ce qui peut être utile pour
résoudre une erreur de pagination de protection en écriture userfaultfd.
UFFDIO_WRITEPROTECT_MODE_DONTWAKE
Quand ce bit de droit est positionné, ne pas réveiller de thread qui attend la
résolution d'une erreur de pagination après l'opération. Cela ne peut être indiqué
que si UFFDIO_WRITEPROTECT_MODE_WP n'est pas indiqué.
Cette opération ioctl(2) renvoie 0 en cas de succès. En cas d'erreur, -1 est renvoyé et
errno est positionné pour indiquer l'erreur. Parmi les erreurs possibles :
EINVAL Le champ start ou len de la structure ufdio_range n'était pas un multiple de la
taille de la page système ; ou len était zéro ; ou la plage indiquée n'était pas
valable pour une autre raison.
EAGAIN Le processus a été interrompu ; réessayez cet appel.
ENOENT La plage indiquée dans range n'est pas valable. Par exemple, l'adresse virtuelle
n'existe pas ou n'est pas enregistrée en mode protection d'écriture userfaultfd.
EFAULT Une erreur générique a été rencontrée lors du traitement.
UFFDIO_CONTINUE
(Depuis Linux 5.13). Résoudre une erreur de pagination mineure en installant des entrées
de tabl de pagination pour les pages existantes dans le cache de page.
Le paramètre argp est un pointeur vers une structure uffdio_continue, telle que présentée
ci-dessous :
struct uffdio_continue {
struct uffdio_range range;
/* Plage pour installer les PTEs for et continue */
__u64 mode; /* Attributs contrôlant le comportement de continue */
__s64 mapped; /* Nombre d'octets projetés ou erreur refusée */0
};
La valeur suivante peut être liée en bits à mode pour modifier le comportement de
l'opération UFFDIO_CONTINUE :
UFFDIO_CONTINUE_MODE_DONTWAKE
Ne pas réveiller le thread qui attend la résolution d'une erreur de page.
Le champ mapped est utilisé par le noyau pour renvoyer le nombre d'octets projetés ou une
erreur de la même manière que UFFDIO_COPY. Si la valeur renvoyée dans le champ mapped ne
correspond pas à celle indiquée dans range.len, l'opération échoue avec l'erreur EAGAIN.
Le champ mapped ne sert qu'à la sortie ; il n'est pas lu par l'opération UFFDIO_CONTINUE.
Cette opération ioctl(2) renvoie 0 en cas de succès. Dans ce cas, toute la zone a été
copiée. En cas d'erreur, -1 est renvoyé et errno est positionné pour indiquer l'erreur.
Parmi les erreurs possibles :
EAGAIN Le nombre d'octets projetés (c'est-à-dire la valeur renvoyée dans le champ mapped)
ne correspond pas à la valeur indiquée dans le champ range.len.
EINVAL range.start ou range.len n'était pas un multiple de la taille de la page du
système ; ou range.len était de zéro ; ou la plage indiquée n'était pas valable.
EINVAL Un bit non valable a été indiqué dans le champ mode.
EEXIST Une ou plusieurs pages ont déjà été projetées dans la plage donnée.
ENOENT Le processus fautif a modifié sa structure de mémoire virtuelle en même temps
qu'une opération UFFDIO_COTINUE remarquable.
ENOMEM L'allocation de la mémoire nécessaire pour installer les projetctions de tables de
pages a échoué.
EFAULT Aucune page existante n'a été trouvée dans le cache de page pour la plage donnée.
ESRCH Le processus fautif a quitté au moment de l'opération UFFDIO_CONTINUE.
VALEUR RENVOYÉE
Voir les descriptions des opérations individuelles ci-dessus.
ERREURS
Voir les descriptions des opérations individuelles ci-dessus. En outre, les erreurs
générales suivantes peuvent se produire pour toutes les opérations décrites ci-dessus :
EFAULT argp pointe vers une adresse illégale.
EINVAL (Pour toutes les opérations, sauf UFFDIO_API). L'objet userfaultfd n'a pas encore
été activé (avec l'opération UFFDIO_API).
STANDARDS
Ces opérations ioctl(2) sont spécifiques à Linux.
BOGUES
Afin de détecter les fonctionnalités userfault disponibles et d'activer des sous-parties
de celles-ci, le descripteur de fichier userfaultfd doit être fermé après la première
opération UFFDIO_API qui recherche la disponibilité des fonctionnalités, puis réouvert
avant la deuxième opération UFFDIO_API qui active les fonctionnalités désirées.
EXEMPLES
Voir userfaultfd(2).
VOIR AUSSI
ioctl(2), mmap(2), userfaultfd(2)
Documentation/admin-guide/mm/userfaultfd.rst dans l'arborescence des sources du noyau
Linux
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 Jean-Philippe MENGUAL
<jpmengual@debian.org>
Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General
Public License version 3 ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ 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⟩.