.\" -*- coding: UTF-8 -*-
.\" Copyright (c) 2017, Oracle. All rights reserved.
.\"
.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" .
.\" %%%LICENSE_END
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH IOCTL_GETFSMAP 2 "9 juin 2020" Linux "Manuel du programmeur Linux"
.SH NOM
ioctl_getfsmap \- récupérer la topographie physique du système de fichiers
.SH SYNOPSIS
\fB#include \fP
.br
\fB#include \fP
.br
\fB#include \fP
.PP
\fBint ioctl(int \fP\fIfd\fP\fB, FS_IOC_GETFSMAP, struct fsmap_head * \fP\fIarg\fP\fB);\fP
.SH DESCRIPTION
Cette opération \fBioctl\fP(2) récupère les plans de domaine (extent) d'un
système de fichiers. Ces informations peuvent être utilisées, entre autres,
pour rechercher les fichiers associés à un bloc physique, analyser l'espace
libre, ou chercher les blocs connus comme défectueux.
.PP
Le seul paramètre de cette opération doit être un pointeur vers une \fIstruct
fsmap_head\fP unique\ :
.PP
.in +4n
.EX
struct fsmap {
__u32 fmr_device; /* ID périphérique */
__u32 fmr_flags; /* Attributs de plan */
__u64 fmr_physical; /* Adresse du segment de périphérique */
__u64 fmr_owner; /* ID du propriétaire */
__u64 fmr_offset; /* Adresse du segment de fichier */
__u64 fmr_length; /* Longueur du segment */
__u64 fmr_reserved[3]; /* Obligatoirement à zéro */
};
struct fsmap_head {
__u32 fmh_iflags; /* Attributs de contrôle */
__u32 fmh_oflags; /* Attributs de sortie */
__u32 fmh_count; /* # of entries in array incl. input */
__u32 fmh_entries; /* Nb d’entrées remplies (sortie) */
__u64 fmh_reserved[6]; /* Obligatoirement à zéro */
struct fsmap fmh_keys[2]; /* Clés basse et haute pour
la recherche de plan */
struct fsmap fmh_recs[]; /* Enregistrements renvoyés */
};
.EE
.in
.PP
Les deux éléments de tableau \fIfmh_keys\fP indiquent la clé la plus basse et
la plus haute pour laquelle l'application veut les informations du plan
physique par rétro\-représentation. Une clé de rétro\-représentation
(«\ retro\-mapping key\ ») consiste dans la séquence (périphérique, bloc,
propriétaire, position). Les champs du propriétaire et de la position font
partie de la clé car certains systèmes de fichiers prennent en charge le
partage de blocs physiques entre plusieurs fichiers, ils peuvent donc
renvoyer plusieurs associations pour un bloc physique donné.
.PP
.\"
Les plans des systèmes de fichiers sont copiés dans un tableau \fIfmh_recs\fP,
qui suit immédiatement les données d'en\-tête.
.SS "Champs de la structure fsmap_head"
Le champ \fIfmh_iflags\fP est un masque de bit passé au noyau pour modifier la
sortie. Aucun attribut n'est actuellement défini, l'appelant doit donc
positionner cette valeur à zéro.
.PP
Le champ \fIfmh_oflags\fP est un masque de bit d'attributs positionnés par le
noyau concernant les plans renvoyés. Si \fBFMH_OF_DEV_T\fP est positionné, le
champ \fIfmr_device\fP représente une structure \fIdev_t\fP contenant les numéros
majeur et mineur du périphérique bloc.
.PP
Le champ \fIfmh_count\fP contient le nombre d'éléments du tableau à passer au
noyau. Si cette valeur vaut \fB0\fP, \fIfmh_entries\fP sera positionné au nombre
d'enregistrements qui auraient été renvoyés avec un tableau plus grand\ ;
aucune information de plan ne sera renvoyée.
.PP
Le champ \fIfmh_entries\fP contient le nombre d'éléments du tableau \fIfmh_recs\fP
qui contiennent des informations utiles.
.PP
.\"
Le champ \fIfmh_reserved\fP doit être positionné à zéro.
.SS Clés
Les deux enregistrements de clés \fIfsmap_head.fmh_keys\fP indiquent les
enregistrements de domaines le plus bas et le plus haut de l'espace de clés
(keyspace) pour lequel l'appelant a demandé le renvoi. Un système de
fichiers qui peut partager des blocs entre les fichiers exige probablement
la série (\fIdevice\fP, \fIphysical\fP, \fIowner\fP, \fIoffset\fP, \fIflags\fP) pour
n'indexer que les enregistrements de plan de système de fichiers. Les
systèmes de fichiers classiques qui ne permettent pas ce partage pourraient
identifier n'importe quel enregistrement avec uniquement (\fIdevice\fP,
\fIphysical\fP, \fIflags\fP). Par exemple, si la clé basse est positionnée sur
(8:0, 36864, 0, 0, 0), le système de fichiers ne renverra que les
enregistrements des domaines commençant ou se trouvant après 36\ Kio sur le
disque. Si la clé haute est positionnée sur (8:0, 1048576, 0, 0, 0), seuls
les enregistrements inférieurs à 1\ Mio seront renvoyés. Le format de
\fIfmr_device\fP dans les clés doit correspondre au format de ces mêmes champs
dans les enregistrements de sortie, comme défini ci\-dessous. Par convention,
le champ \fIfsmap_head.fmh_keys[0]\fP doit contenir la clé basse et le champ
\fIfsmap_head.fmh_keys[1]\fP la clé haute pour la requête.
.PP
.\"
Par commodité, si \fIfmr_length\fP est positionné dans la clé basse, il sera
ajouté en fonction à \fIfmr_block\fP ou à \fIfmr_offset\fP. L'appelant peut tirer
parti de cette subtilité en positionnant les appels suivants à travers la
copie de \fIfsmap_head.fmh_recs[fsmap_head.fmh_entries\ \-\ 1]\fP dans la clé
basse. La fonction \fIfsmap_advance\fP (définie dans \fIlinux/fsmap.h\fP) fournit
cette possibilité.
.SS "Champs de la structure fsmap"
Le champ \fIfmr_device\fP identifie uniquement le périphérique de stockage
sous\-jacent. Si l'attribut \fBFMH_OF_DEV_T\fP est positionné dans le champ
\fIfmh_oflags\fP de l'en\-tête, ce champ contient un \fIdev_t\fP à partir duquel
les numéros majeur et mineur peuvent être extraits. Si l'attribut n'est pas
positionné, ce champ contient une valeur qui doit être unique pour chaque
périphérique de stockage.
.PP
Le champ \fIfmr_physical\fP contient l'adresse sur le disque du domaine en
octets.
.PP
Le champ \fIfmr_owner\fP contient le propriétaire du domaine. Il s'agit d'un
numéro d'inœud, sauf si \fBFMR_OF_SPECIAL_OWNER\fP est positionné dans le champ
\fIfmr_flags\fP, auquel cas la valeur est déterminée par le système de
fichiers. Voir la section ci\-dessous concernant les valeurs du propriétaire
pour plus de détails.
.PP
Le champ \fIfmr_offset\fP contient l'adresse logique sur l'enregistrement du
plan en octets. Ce champ n'a aucun sens si les attributs
\fBFMR_OF_SPECIAL_OWNER\fP ou \fBFMR_OF_EXTENT_MAP\fP sont positionnés dans
\fIfmr_flags\fP.
.PP
Le champ \fIfmr_length\fP contient la longueur du domaine en octets.
.PP
Le champ \fIfmr_flags\fP est un masque de bit des attributs d'état du
domaine. Les bits sont\ :
.RS 0.4i
.TP
\fBFMR_OF_PREALLOC\fP
Le domaine est alloué mais pas encore écrit.
.TP
\fBFMR_OF_ATTR_FORK\fP
Ce domaine contient des données d'attributs étendus.
.TP
\fBFMR_OF_EXTENT_MAP\fP
Ce domaine contient des informations sur le plan de domaine pour le
propriétaire.
.TP
\fBFMR_OF_SHARED\fP
Certaines parties de ce domaine peuvent être partagées.
.TP
\fBFMR_OF_SPECIAL_OWNER\fP
Le champ \fIfmr_owner\fP contient une valeur spéciale et non un numéro d'inœud.
.TP
\fBFMR_OF_LAST\fP
Il s'agit du dernier enregistrement du jeu de données.
.RE
.PP
.\"
Le champ \fIfmr_reserved\fP sera positionné à zéro.
.SS "valeur du propriétaire"
Généralement, la valeur du champ \fIfmr_owner\fP pour les domaines qui ne sont
pas des métadonnées devrait être un numéro d'inœud. Cependant, les systèmes
de fichiers ne sont pas obligés de signaler les numéros d'inœud\ ; ils
peuvent plutôt renvoyer \fBFMR_OWN_UNKNOWN\fP si le numéro d'inœud ne peut pas
être récupéré facilement, si l'appelant n'a pas assez de privilèges, si le
système de fichiers ne gère pas les numéros d'inœud stables, ou pour toute
autre raison. Si un système de fichiers souhaite conditionner l'envoi des
numéros d'inœuds aux capacités du processus, il est fortement recommandé
d'utiliser la capacité \fBCAP_SYS_ADMIN\fP à cette fin.
.TP
Les valeurs spéciales de propriétaire suivantes sont communes à tous les systèmes de fichiers\ :
.RS 0.4i
.TP
\fBFMR_OWN_FREE\fP
Espace libre.
.TP
\fBFMR_OWN_UNKNOWN\fP
Ce domaine est utilisé mais son propriétaire n'est pas connu ou n’est pas
facilement récupérable.
.TP
\fBFMR_OWN_METADATA\fP
Ce domaine est une métadonnée d'un système de fichiers.
.RE
.PP
XFS peut renvoyer les valeurs spéciales de propriétaire suivantes\ :
.RS 0.4i
.TP
\fBXFS_FMR_OWN_FREE\fP
Espace libre.
.TP
\fBXFS_FMR_OWN_UNKNOWN\fP
Ce domaine est utilisé mais son propriétaire n'est pas connu ou n’est pas
facilement récupérable.
.TP
\fBXFS_FMR_OWN_FS\fP
Les métadonnées de système de fichiers statiques qui existent à une adresse
fixe. Il s'agit de superblocs AG et des en\-têtes AGF, AGFL et AGI.
.TP
\fBXFS_FMR_OWN_LOG\fP
Le journal du système de fichiers.
.TP
\fBXFS_FMR_OWN_AG\fP
Métadonnées du groupe d'allocation telles que les btrees de l'espace libre
ou du rétro\-plan.
.TP
\fBXFS_FMR_OWN_INOBT\fP
L'inœud et les btrees de l'inœud libre.
.TP
\fBXFS_FMR_OWN_INODES\fP
Enregistrements de l'inœud.
.TP
\fBXFS_FMR_OWN_REFC\fP
Informations du compte de référence.
.TP
\fBXFS_FMR_OWN_COW\fP
Ce domaine est utilisé pour préparer une copie sur écriture.
.TP
\fBXFS_FMR_OWN_DEFECTIVE:\fP
Cette extension a été marquée comme étant défectueuse, soit par le système
de fichiers, soit par le périphérique sous\-jacent.
.RE
.PP
ext4 peut renvoyer les valeurs spéciales de propriétaire\ :
.RS 0.4i
.TP
\fBEXT4_FMR_OWN_FREE\fP
Espace libre.
.TP
\fBEXT4_FMR_OWN_UNKNOWN\fP
Ce domaine est utilisé mais son propriétaire n'est pas connu ou n’est pas
facilement récupérable.
.TP
\fBEXT4_FMR_OWN_FS\fP
Métadonnées du système de fichiers statiques qui existent à une adresse
fixe. Il s'agit du superbloc et des descripteurs de groupe.
.TP
\fBEXT4_FMR_OWN_LOG\fP
Le journal du système de fichiers.
.TP
\fBEXT4_FMR_OWN_INODES\fP
Enregistrements de l'inœud.
.TP
\fBEXT4_FMR_OWN_BLKBM\fP
Plan de bit de bloc.
.TP
\fBEXT4_FMR_OWN_INOBM\fP
Plan de bit d'inœud.
.RE
.SH "VALEUR RENVOYÉE"
En cas d'erreur, la valeur de retour est \fB\-1\fP et \fIerrno\fP est définie pour
préciser l'erreur.
.SH ERREURS
L'erreur inscrite dans \fIerrno\fP peut être, entre autres, une des suivantes\ :
.TP
\fBEBADF\fP
\fIfd\fP n'est pas ouvert en lecture.
.TP
\fBEBADMSG\fP
Le système de fichiers a détecté une erreur de somme de contrôle dans les
métadonnées.
.TP
\fBEFAULT\fP
Le pointeur fourni ne correspond à aucune adresse mémoire valable.
.TP
\fBEINVAL\fP
Le tableau n'est pas assez long, les clés ne pointent pas vers une partie
valable du système de fichiers, la clé basse pointe vers un point de
l'espace d'adresses de stockage physique du système de fichiers plus élevé
que la clé haute ou une valeur non nulle a été inscrite dans un champ qui
doit contenir zéro.
.TP
\fBENOMEM\fP
Pas assez de mémoire pour traiter la requête.
.TP
\fBEOPNOTSUPP\fP
Le système de fichiers ne prend pas en charge cette commande.
.TP
\fBEUCLEAN\fP
Les métadonnées du système de fichiers sont corrompues et doivent être
réparées.
.SH VERSIONS
L'opération \fBFS_IOC_GETFSMAP\fP est apparue pour la première fois dans
Linux\ 4.12.
.SH CONFORMITÉ
Cette API est spécifique à Linux. Tous les systèmes de fichiers ne la gèrent
pas.
.SH EXEMPLES
Voir \fIio/fsmap.c\fP dans les \fIxfsprogs\fP pour un programme d'exemple.
.SH "VOIR AUSSI"
\fBioctl\fP(2)
.SH COLOPHON
Cette page fait partie de la publication\ 5.10 du projet \fIman\-pages\fP
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/.
.PP
.SH TRADUCTION
La traduction française de cette page de manuel a été créée par
Christophe Blaess ,
Stéphan Rafin ,
Thierry Vignaud ,
François Micaux,
Alain Portal ,
Jean-Philippe Guérard ,
Jean-Luc Coulon (f5ibh) ,
Julien Cristau ,
Thomas Huriaux ,
Nicolas François ,
Florentin Duneau ,
Simon Paillard ,
Denis Barbier ,
David Prévot
et
Jean-Philippe MENGUAL
.
.PP
Cette traduction est une documentation libre ; veuillez vous reporter à la
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License version 3
.UE
concernant les conditions de copie et
de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.
.PP
Si vous découvrez un bogue dans la traduction de cette page de manuel,
veuillez envoyer un message à
.MT debian-l10n-french@lists.debian.org
.ME .