statx - Afficher l'état d'un fichier (étendu)
Bibliothèque C standard (libc, -lc)
#define _GNU_SOURCE /* Consultez feature_test_macros(7) */
#include <fcntl.h> /* Définitions des constantes AT_* */
#include <sys/stat.h>
int statx(int dirfd, const char *restrictnom_chemin, intflags,
unsigned int mask, struct statx *restrict statxbuf);
Cette fonction renvoie des informations sur un fichier, le
stockant dans le tampon pointé par statxbuff. Le tampon
renvoyé est une structure du type suivant :
struct statx {
__u32 stx_mask; /* Masque d'octets indiquant
les champs remplis */
__u32 stx_blksize; /* Taille de bloc pour les E/S du système de fichiers */
__u64 stx_attributes; /* Indicateurs d'attribut de fichier supplémentaire */
__u32 stx_nlink; /* Nombre de liens directs */
__u32 stx_uid; /* UID du propriétaire */
__u32 stx_gid; /* GID du propriétaire */
__u16 stx_mode; /* Type de fichier et mode */
__u64 stx_ino; /* Numéro d'inœud */
__u64 stx_size; /* Taille totale en octets */
__u64 stx_blocks; /* Nombre de blocs de 512 o alloués */
__u64 stx_attributes_mask;
/* Masque pour montrer ce qui est pris en charge
dans stx_attributes */
/* Les champs suivants sont des fichiers d'horodatage */
struct statx_timestamp stx_atime; /* Dernier accès */
struct statx_timestamp stx_btime; /* Création */
struct statx_timestamp stx_ctime; /* Dernier changement d'état */
struct statx_timestamp stx_mtime; /* Dernière modification */
/* Si ce fichier représente un périphérique, alors les
deux champs suivants contiennent l'identifiant du périphérique */
__u32 stx_rdev_major; /* Identifiant majeur */
__u32 stx_rdev_minor; /* Identifiant mineur */
/* Les deux champs suivants contiennent l'identifiant du périphérique
contenant le système de fichier où est situé le fichier */
__u32 stx_dev_major ; /* ID majeur */
__u32 stx_dev_minor ; /* ID mineur */
__u64 stx_mnt_id; /* ID de montage */
/* Restrictions d'alignement d'E/S directes */
__u32 stx_dio_mem_align;
__u32 stx_dio_offset_align;
};
Les horodatages de fichier sont des structures du type
suivant :
struct statx_timestamp {
__s64 tv_sec; /* Secondes depuis l'Epoch (temps UNIX) */
__u32 tv_nsec; /* Nanosecondes depuis tv_sec */
};
(Notez que l'espace réservé et le remplissage sont
ommis.)
Pour accéder à l'état d'un fichier, aucune
autorisation n'est requise sur le fichier lui-même, mais dans le cas
de statx() avec un nom de chemin, la permission d'exécution
(recherche) est requise sur tous les répertoires du nom_chemin
qui mènent au fichier.
statx() utilise nom_chemin, dirfd, et
flags pour identifier le fichier cible d'une des façons
suivantes :
- Un nom de chemin absolu
- Si nom_chemin commence avec une barre oblique (slash), alors c'est
un nom de chemin absolu qui identifie le fichier cible. Dans ce cas,
dirfd est ignoré.
- Nom de chemin relatif
- Si nom_chemin est une chaîne qui commence par un
caractère autre qu'une barre oblique et que dirfd est
AT_FDCWD, alors nom_chemin est un chemin relatif qui est
interprété comme étant relatif au répertoire
courant du processus appelant.
- Un répertoire de nom de
chemin relatif
- Si nom_chemin est une chaîne qui commence par un
caractère autre qu'une barre oblique et dirfd est un
descripteur de fichier qui réfère à un
répertoire, alors nom_chemin est un nom de chemin relatif
qui est interprété relativement au répertoire auquel
fait référence dirfd. (Consulter openat(2)
pour une explication de son utilité.)
- Avec un descripteur de
fichier
- Si nom_chemin est une chaîne vide et que le drapeau
AT_EMPTY_PATH est spécifié dans flags (voir
ci-dessous), alors le fichier cible est celui auquel fait
référence le descripteur de fichier dirfd.
flags peut être utilisé pour influencer une
recherche par nom de chemin. Une valeur pour flags est construite par
une association OU binaire de zéro ou plus des constantes
suivantes :
- AT_EMPTY_PATH
- Si nom_chemin est une chaîne vide, opérer sur le
fichier référencé par dirfd (qui peut avoir
été obtenu en utilisant le drapeau O_PATH de
open(2)). Dans ce cas, dirfd peut faire
référence à tout type de fichier, et pas seulement
à un répertoire.
- Si dirfd est AT_FDCWD, l'appel opère sur le
répertoire de travail actuel.
- AT_NO_AUTOMOUNT
- Ne pas attacher automatiquement le composant terminal (nom de base) de
nom_chemin s'il s'agit d'un répertoire qui est un point de
montage automatique. Cela permet à l'appelant de rassembler les
attributs d'un point de montage automatique (plutôt que
l'emplacement qu'il attacherait). Ce drapeau n'a aucun effet si le point
de montage est déjà attaché.
- Le drapeau AT_NO_AUTOMOUNT peut être utilisé dans des
outils qui analysent les répertoires pour éviter un montage
automatique en masse d'un répertoire contenant des points de
montage automatique.
- stat(2), lstat(2) et fstatat(2) agissent tous comme
si AT_NO_AUTOMOUNT a été défini.
- AT_SYMLINK_NOFOLLOW
- Si nom_chemin est un lien symbolique, ne pas le
déréférencer, mais renvoyer des informations sur le
lien lui‐même, comme le fait lstat(2).
flags peut aussi être utilisé pour
contrôler quelle sorte de synchronisation le noyau effectuera lors
d'une demande d'un fichier sur un système de fichiers distant. Cela
est fait par l'utilisation d'un OU binaire d'une des valeurs
suivantes :
- AT_STATX_SYNC_AS_STAT
- Faire tout ce que fait stat(2). C'est l'option par défaut et
c'est très spécifique au système de fichiers.
- AT_STATX_FORCE_SYNC
- Forcer les attributs à être synchronisés avec le
serveur. Cela peut nécessiter qu'un système de fichiers en
réseau réalise une réécriture de
données pour avoir des horodatages corrects.
- AT_STATX_DONT_SYNC
- Ne rien synchroniser, mais prendre plutôt ce que le système
a mis en cache si possible. Cela peut signifier que les informations
renvoyées sont approximatives, mais, sur un système de
fichiers en réseau, cela peut ne pas impliquer d'aller-retour vers
le serveur, même si aucun bail n'est détenu.
L'argument mask à statx() est utilisé
pour dire au noyau quels champs intéressent l'appelant. mask
est une combinaison liée par un OU binaire des constantes
suivantes :
STATX_TYPE |
Nécessite stx_mode et S_IFMT |
STATX_MODE |
Nécessite stx_mode et ~S_IFMT |
STATX_NLINK |
Nécessite stx_nlink |
STATX_UID |
Nécessite stx_uid |
STATX_GID |
Nécessite stx_gid |
STATX_ATIME |
Nécessite stx_atime |
STATX_MTIME |
Nécessite stx_mtime |
STATX_CTIME |
Nécessite stx_ctime |
STATX_INO |
Nécessite stx_ino |
STATX_SIZE |
Nécessite stx_size |
STATX_BLOCKS |
Nécessite stx_blocks |
STATX_BASIC_STATS |
[Tous ceux ci-dessus] |
STATX_BTIME |
Nécessite stx_btime |
STATX_ALL |
Identique à STATX_BASIC_STATS | STATX_BTIME. |
|
La commande est obsolète et ne devrait pas être
utilisée. |
STATX_MNT_ID |
Nécessite stx_mnt_id (depuis Linux 5.8) |
STATX_DIOALIGN |
Nécessite stx_dio_mem_align et stx_dio_offset_align |
|
(depuis Linux 6.1 ; prise en charge selon le
système de fichiers) |
Remarquez que, en général, le noyau ne rejette
pas des valeurs dans mask autres que celles ci-dessus. (Pour une
exception, voir EINVAL dans les erreurs.) Au lieu de cela, il informe
simplement l'appelant des valeurs prises en charge par ce noyau et ce
système de fichiers à l'aide du champ statx.stx_mask.
Par conséquent, ne pas se contenter de mettre mask
à UINT_MAX (tous les bits sont mis), car un ou plusieurs bits
peuvent, à l'avenir, être utilisés pour
spécifier une extension au tampon.
L'information d'état pour le fichier cible est
renvoyée dans la structure statx pointée par
statxbuf. On y trouve stx_mask qui indique quelles autres
informations ont été renvoyées. stx_mask a le
même format que l'argument mask et les bits y sont
définis pour indiquer quels champs ont été remplis.
Il convient de noter que le noyau peut renvoyer des champs qui
n'ont pas été demandés et peut ne pas renvoyer des
champs qui ont été demandés, en fonction de ce que le
système de fichiers sous-jacent prend en charge. (Les champs qui
reçoivent des valeurs alors qu'ils ne sont pas demandés
peuvent être simplement ignorés.) Dans les deux cas,
stx_mask ne sera pas égal à mask.
Si un système de fichiers ne prend pas en charge un champ
ou qu'il y a une valeur non représentable (par exemple, un fichier
d'un type exotique), alors le bit masqué correspondant à ce
champ sera effacé de stx_mask même si l'utilisateur l'a
demandé et une valeur fictive sera remplie à des fins de
compatibilité s'il en existe une (par exemple un UID ou un GID
fictifs pourront être indiqués pour monter sous certaines
circonstances).
Un système de fichiers peut également remplir des
champs que l'appelant n'a pas demandé s'il dispose de valeurs pour
ces champs et si l'information est disponible sans coût
supplémentaire. Si cela se produit, les bits correspondants seront
mis dans stx_mask.
Note : pour la performance et des raisons de
simplicité, des champs différents dans la structure
statx devraient contenir les informations d'état des divers
moments de l'exécution de l'appel système. Par exemple, si
stx_mode ou stx_uid est changé par un autre processus
par un appel chmod(2) ou chown(2), stat() devrait
renvoyer l'ancien stx_mode avec le nouveau stx_uid, ou
l'ancien stx_uid avec le nouveau stx_mode.
À part ceux du stx_mask (qui est décrit
ci-dessus), les champs de la structure statx sont :
- stx_blksize
- La taille de bloc
« préférée » pour des
entrées-sorties du système de fichiers efficaces. (Des
écritures par blocs plus petits peuvent entraîner un cycle
lecture/modification/réécriture inefficace.)
- stx_attributes
- Informations supplémentaires sur l'état du fichier (voir
ci-dessous pour plus d'informations).
- stx_nlink
- Le nombre de liens directs sur un fichier.
- stx_uid
- Ce champ contient l'UID du propriétaire du fichier.
- stx_gid
- Ce champ contient l'identifiant du groupe propriétaire du
fichier.
- stx_mode
- Le mode et type de fichier. Voir inode(7) pour plus de
détails.
- stx_ino
- Le numéro d'inœud du fichier.
- stx_size
- La taille du fichier (s'il s'agit d'un fichier ordinaire ou d'un lien
symbolique) en octets. La taille d'un lien symbolique est la longueur du
chemin d'accès qu'il vise, sans octet NULL final.
- stx_blocks
- Le nombre de blocs de 512 octets alloués au fichier sur le
support. (Cette valeur peut être inférieure à
st_size/512 si le fichier a des trous.)
- stx_attributes_mask
- Un masque indiquant quels bits dans stx_attributes sont pris en
charge par le VFS et le système de fichiers.
- stx_atime
- L'horodatage du dernier accès au fichier.
- stx_btime
- L'horodatage de création du fichier.
- stx_ctime
- L'horodatage du dernier changement d'état du fichier.
- stx_mtime
- L'horodatage de la dernière modification du fichier.
- stx_dev_major
et stx_dev_minor
- Le périphérique sur lequel réside ce fichier
(inœud).
- stx_rdev_major
et stx_rdev_minor
- Le périphérique que ce fichier (inœud)
représente si le fichier est de type périphérique
bloc ou caractère.
- stx_mnt_id
- L'identifiant du montage contenant le fichier. C'est le même
numéro que celui rapporté par name_to_handle_at(2) et
qui correspond au numéro dans le premier champ d'un des
enregistrements dans /proc/self/mountinfo.
- stx_dio_mem_align
- L'alignement (en octets) est requis pour les tampons de mémoire
utilisateur pour des E/S directes (O_DIRECT) sur ce fichier, ou 0
si les E/S directes ne sont pas prises en charge sur ce fichier.
- STATX_DIOALIGN (stx_dio_mem_align et
stx_dio_offset_align) est pris en charge sur les
périphériques bloc depuis Linux 6.1. La prise en
charge des fichiers ordinaires varie selon le système de
fichiers ; il est pris en charge par ext4, f2fs et xfs depuis
Linux 6.1.
- stx_dio_offset_align
- L'alignement (en octets) est requis pour les décalage sdes fichiers
et la longueur des segments d'E/S pour des E/S directes (O_DIRECT)
sur ce fichier, ou 0 si les E/S directes ne sont pas prises en charge sur
ce fichier. Il sera uniquement différent de zéro si
stx_dio_mem_align est différent de zéro et
vice-versa.
Pour plus d'information sur les champs ci-dessus, voir
inode(7).
Le champ stx_attributes contient un ensemble de drapeaux
liés par un OU binaire qui indiquent les attributs
additionnels du fichier. Veuillez noter que tout attribut qui n'est pas
indiqué comme pris en charge par stx_attributes_mask n'a pas
de valeur utilisable ici. Les bits dans stx_attributes_mask
correspondent bit par bit à stx_attributes.
Les drapeaux sont de la forme suivante :
- STATX_ATTR_COMPRESSED
- Le fichier est compressé par le système de fichiers et son
accès peut nécessiter des ressources
supplémentaires.
- STATX_ATTR_IMMUTABLE
- Le fichier ne peut pas être modifié : il ne peut
être ni effacé, ni renommé, aucun lien direct ne peut
être créé vers ce fichier et aucune donnée ne
peut y être écrite. Consulter chattr(1).
- STATX_ATTR_APPEND
- Le fichier ne peut être ouvert qu'en mode ajout pour
l'écriture. L'écriture par accès aléatoire
n'est pas permise. Voir chattr(1).
- STATX_ATTR_NODUMP
- Le fichier n'est pas candidat à une sauvegarde lorsqu'un programme
de sauvegarde tel que dump(8) est lancé. Voir
chattr(1).
- STATX_ATTR_ENCRYPTED
- Une clé est requise pour que le fichier soit chiffré par le
système de fichiers.
- STATX_ATTR_VERITY
(depuis Linux 5.5)
- Le fichier a fs-verity d'activé. Il est impossible d'y
écrire et toutes les lectures seront vérifiées par
rapport à un hachage cryptographique qui couvre l'ensemble du
fichier (par exemple, grâce à un arbre de Merkel).
- STATX_ATTR_DAX
(depuis Linux 5.8)
- Le fichier est dans l'état DAX (accès direct au processeur).
L'état DAX essaie de minimiser les effets du cache du logiciel
à la fois pour les mappages de mémoire et les
Entrées/Sorties de ce fichier. Cela nécessite un
système de fichiers qui a été configuré pour
prendre en charge DAX.
- DAX suppose généralement que tous les accès se font
à travers des instructions de chargement/stockage du processeur, ce
qui peut minimiser la surcharge pour les petits accès, mais peut
avoir un effet négatif sur l'utilisation du processeur pour les
transferts importants.
- Le fichier d'E/S est fait directement vers/depuis les tampons de l'espace
utilisateur et les E/S mappées en mémoire peuvent
être effectuées avec des mappages directs en mémoire
qui contournent le cache de page du noyau.
- Alors que la propriété DAX a tendance à
entraîner un transfert synchrone des données, cela ne
procure pas les mêmes garanties que le drapeau O_SYNC (voir
open(2)), où les données et les
métadonnées sont transférées ensemble.
- Un fichier DAX devrait accepter d'être mappé avec le drapeau
MAP_SYNC, ce qui permet à un programme d'utiliser les
instructions de vidage du cache du processeur pour faire persister les
opérations de stockage du processeur sans un fsync(2)
explicite. Voir mmap(2) pour plus d'informations.
En cas de succès, zéro est renvoyé. En cas
d'erreur, -1 est renvoyé et errno est définie
pour préciser l'erreur.
- EACCES
- La permission de parcours est refusée pour un des
répertoires contenu dans le chemin nom_chemin. (Consultez
aussi path_resolution(7).)
- EBADF
- pathname est relatif mais dirfd n'est ni AT_FDWCD ni
un descripteur de fichier valable.
- EFAULT
- nom_chemin ou statxbuf est NULL ou pointe en dehors de
l'espace d'adressage accessible.
- EINVAL
- flags contient un attribut non valable.
- EINVAL
- Drapeau réservé indiqué dans mask.
(Actuellement, il y a un tel drapeau, désigné par la
constante STATX_RESERVED, avec la valeur 0x80000000U.)
- ELOOP
- Trop de liens symboliques rencontrés dans le nom de chemin.
- ENAMETOOLONG
- nom_chemin est trop long.
- ENOENT
- Un composant du chemin nom_chemin n'existe pas, ou
nom_chemin est une chaîne vide et AT_EMPTY_PATH
n'était pas spécifié dans flags.
- ENOMEM
- Pas assez de mémoire (mémoire noyau).
- ENOTDIR
- Un composant du préfixe du chemin nom_chemin n'est pas un
répertoire ou nom_chemin est relatif, et le descripteur de
fichier dirfd est associé à un fichier, pas à
un répertoire.
statx() a été ajouté dans
Linux 4.11 ; la prise en charge de la bibliothèque a
été ajoutée dans glibc 2.28.
statx() est spécifique à Linux.
ls(1), stat(1), access(2), chmod(2),
chown(2), name_to_handle_at(2), readlink(2),
stat(2), utime(2), proc(5), capabilities(7),
inode(7), symlink(7)
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
bubu <bubub@no-log.org>
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.