statx(2) System Calls Manual statx(2) NOM statx - Afficher l'etat d'un fichier (etendu) BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #define _GNU_SOURCE /* Consultez feature_test_macros(7) */ #include /* Definitions des constantes AT_* */ #include int statx(int dirfd, const char *restrictnom_chemin, intflags, unsigned int mask, struct statx *restrict statxbuf); DESCRIPTION Cette fonction renvoie des informations sur un fichier, le stockant dans le tampon pointe par statxbuff. Le tampon renvoye 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 systeme de fichiers */ __u64 stx_attributes; /* Indicateurs d'attribut de fichier supplementaire */ __u32 stx_nlink; /* Nombre de liens directs */ __u32 stx_uid; /* UID du proprietaire */ __u32 stx_gid; /* GID du proprietaire */ __u16 stx_mode; /* Type de fichier et mode */ __u64 stx_ino; /* Numero d'inoeud */ __u64 stx_size; /* Taille totale en octets */ __u64 stx_blocks; /* Nombre de blocs de 512 o alloues */ __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 acces */ struct statx_timestamp stx_btime; /* Creation */ struct statx_timestamp stx_ctime; /* Dernier changement d'etat */ struct statx_timestamp stx_mtime; /* Derniere modification */ /* Si ce fichier represente un peripherique, alors les deux champs suivants contiennent l'identifiant du peripherique */ __u32 stx_rdev_major; /* Identifiant majeur */ __u32 stx_rdev_minor; /* Identifiant mineur */ /* Les deux champs suivants contiennent l'identifiant du peripherique contenant le systeme de fichier ou est situe 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 reserve et le remplissage sont ommis.) Invoking statx(): Pour acceder a l'etat d'un fichier, aucune autorisation n'est requise sur le fichier lui-meme, mais dans le cas de statx() avec un nom de chemin, la permission d'execution (recherche) est requise sur tous les repertoires du nom_chemin qui menent au fichier. statx() utilise nom_chemin, dirfd, et flags pour identifier le fichier cible d'une des facons 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 ignore. Nom de chemin relatif Si nom_chemin est une chaine qui commence par un caractere autre qu'une barre oblique et que dirfd est AT_FDCWD, alors nom_chemin est un chemin relatif qui est interprete comme etant relatif au repertoire courant du processus appelant. Un repertoire de nom de chemin relatif Si nom_chemin est une chaine qui commence par un caractere autre qu'une barre oblique et dirfd est un descripteur de fichier qui refere a un repertoire, alors nom_chemin est un nom de chemin relatif qui est interprete relativement au repertoire auquel fait reference dirfd. (Consulter openat(2) pour une explication de son utilite.) Avec un descripteur de fichier Si nom_chemin est une chaine vide et que le drapeau AT_EMPTY_PATH est specifie dans flags (voir ci-dessous), alors le fichier cible est celui auquel fait reference le descripteur de fichier dirfd. flags peut etre utilise pour influencer une recherche par nom de chemin. Une valeur pour flags est construite par une association OU binaire de zero ou plus des constantes suivantes : AT_EMPTY_PATH Si nom_chemin est une chaine vide, operer sur le fichier reference par dirfd (qui peut avoir ete obtenu en utilisant le drapeau O_PATH de open(2)). Dans ce cas, dirfd peut faire reference a tout type de fichier, et pas seulement a un repertoire. Si dirfd est AT_FDCWD, l'appel opere sur le repertoire 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 repertoire qui est un point de montage automatique. Cela permet a l'appelant de rassembler les attributs d'un point de montage automatique (plutot que l'emplacement qu'il attacherait). Ce drapeau n'a aucun effet si le point de montage est deja attache. Le drapeau AT_NO_AUTOMOUNT peut etre utilise dans des outils qui analysent les repertoires pour eviter un montage automatique en masse d'un repertoire contenant des points de montage automatique. stat(2), lstat(2) et fstatat(2) agissent tous comme si AT_NO_AUTOMOUNT a ete defini. AT_SYMLINK_NOFOLLOW Si nom_chemin est un lien symbolique, ne pas le dereferencer, mais renvoyer des informations sur le lien lui-meme, comme le fait lstat(2). flags peut aussi etre utilise pour controler quelle sorte de synchronisation le noyau effectuera lors d'une demande d'un fichier sur un systeme 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 defaut et c'est tres specifique au systeme de fichiers. AT_STATX_FORCE_SYNC Forcer les attributs a etre synchronises avec le serveur. Cela peut necessiter qu'un systeme de fichiers en reseau realise une reecriture de donnees pour avoir des horodatages corrects. AT_STATX_DONT_SYNC Ne rien synchroniser, mais prendre plutot ce que le systeme a mis en cache si possible. Cela peut signifier que les informations renvoyees sont approximatives, mais, sur un systeme de fichiers en reseau, cela peut ne pas impliquer d'aller-retour vers le serveur, meme si aucun bail n'est detenu. L'argument mask a statx() est utilise pour dire au noyau quels champs interessent l'appelant. mask est une combinaison liee par un OU binaire des constantes suivantes : STATX_TYPE Necessite stx_mode et S_IFMT STATX_MODE Necessite stx_mode et ~S_IFMT STATX_NLINK Necessite stx_nlink STATX_UID Necessite stx_uid STATX_GID Necessite stx_gid STATX_ATIME Necessite stx_atime STATX_MTIME Necessite stx_mtime STATX_CTIME Necessite stx_ctime STATX_INO Necessite stx_ino STATX_SIZE Necessite stx_size STATX_BLOCKS Necessite stx_blocks STATX_BASIC_STATS [Tous ceux ci-dessus] STATX_BTIME Necessite stx_btime STATX_ALL Identique a STATX_BASIC_STATS | STATX_BTIME. La commande est obsolete et ne devrait pas etre utilisee. STATX_MNT_ID Necessite stx_mnt_id (depuis Linux 5.8) STATX_DIOALIGN Necessite stx_dio_mem_align et stx_dio_offset_align (depuis Linux 6.1 ; prise en charge selon le systeme de fichiers) Remarquez que, en general, 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 systeme de fichiers a l'aide du champ statx.stx_mask. Par consequent, ne pas se contenter de mettre mask a UINT_MAX (tous les bits sont mis), car un ou plusieurs bits peuvent, a l'avenir, etre utilises pour specifier une extension au tampon. Information renvoyee L'information d'etat pour le fichier cible est renvoyee dans la structure statx pointee par statxbuf. On y trouve stx_mask qui indique quelles autres informations ont ete renvoyees. stx_mask a le meme format que l'argument mask et les bits y sont definis pour indiquer quels champs ont ete remplis. Il convient de noter que le noyau peut renvoyer des champs qui n'ont pas ete demandes et peut ne pas renvoyer des champs qui ont ete demandes, en fonction de ce que le systeme de fichiers sous-jacent prend en charge. (Les champs qui recoivent des valeurs alors qu'ils ne sont pas demandes peuvent etre simplement ignores.) Dans les deux cas, stx_mask ne sera pas egal a mask. Si un systeme de fichiers ne prend pas en charge un champ ou qu'il y a une valeur non representable (par exemple, un fichier d'un type exotique), alors le bit masque correspondant a ce champ sera efface de stx_mask meme si l'utilisateur l'a demande et une valeur fictive sera remplie a des fins de compatibilite s'il en existe une (par exemple un UID ou un GID fictifs pourront etre indiques pour monter sous certaines circonstances). Un systeme de fichiers peut egalement remplir des champs que l'appelant n'a pas demande s'il dispose de valeurs pour ces champs et si l'information est disponible sans cout supplementaire. Si cela se produit, les bits correspondants seront mis dans stx_mask. Note : pour la performance et des raisons de simplicite, des champs differents dans la structure statx devraient contenir les informations d'etat des divers moments de l'execution de l'appel systeme. Par exemple, si stx_mode ou stx_uid est change 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. A part ceux du stx_mask (qui est decrit ci-dessus), les champs de la structure statx sont : stx_blksize La taille de bloc << preferee >> pour des entrees-sorties du systeme de fichiers efficaces. (Des ecritures par blocs plus petits peuvent entrainer un cycle lecture/modification/reecriture inefficace.) stx_attributes Informations supplementaires sur l'etat 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 proprietaire du fichier. stx_gid Ce champ contient l'identifiant du groupe proprietaire du fichier. stx_mode Le mode et type de fichier. Voir inode(7) pour plus de details. stx_ino Le numero d'inoeud 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'acces qu'il vise, sans octet NULL final. stx_blocks Le nombre de blocs de 512 octets alloues au fichier sur le support. (Cette valeur peut etre inferieure a 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 systeme de fichiers. stx_atime L'horodatage du dernier acces au fichier. stx_btime L'horodatage de creation du fichier. stx_ctime L'horodatage du dernier changement d'etat du fichier. stx_mtime L'horodatage de la derniere modification du fichier. stx_dev_major et stx_dev_minor Le peripherique sur lequel reside ce fichier (inoeud). stx_rdev_major et stx_rdev_minor Le peripherique que ce fichier (inoeud) represente si le fichier est de type peripherique bloc ou caractere. stx_mnt_id L'identifiant du montage contenant le fichier. C'est le meme numero que celui rapporte par name_to_handle_at(2) et qui correspond au numero 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 memoire 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 peripheriques bloc depuis Linux 6.1. La prise en charge des fichiers ordinaires varie selon le systeme 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 decalage 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 different de zero si stx_dio_mem_align est different de zero et vice-versa. Pour plus d'information sur les champs ci-dessus, voir inode(7). Attributs de fichier Le champ stx_attributes contient un ensemble de drapeaux lies par un OU binaire qui indiquent les attributs additionnels du fichier. Veuillez noter que tout attribut qui n'est pas indique 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 a stx_attributes. Les drapeaux sont de la forme suivante : STATX_ATTR_COMPRESSED Le fichier est compresse par le systeme de fichiers et son acces peut necessiter des ressources supplementaires. STATX_ATTR_IMMUTABLE Le fichier ne peut pas etre modifie : il ne peut etre ni efface, ni renomme, aucun lien direct ne peut etre cree vers ce fichier et aucune donnee ne peut y etre ecrite. Consulter chattr(1). STATX_ATTR_APPEND Le fichier ne peut etre ouvert qu'en mode ajout pour l'ecriture. L'ecriture par acces aleatoire n'est pas permise. Voir chattr(1). STATX_ATTR_NODUMP Le fichier n'est pas candidat a une sauvegarde lorsqu'un programme de sauvegarde tel que dump(8) est lance. Voir chattr(1). STATX_ATTR_ENCRYPTED Une cle est requise pour que le fichier soit chiffre par le systeme de fichiers. STATX_ATTR_VERITY (depuis Linux 5.5) Le fichier a fs-verity d'active. Il est impossible d'y ecrire et toutes les lectures seront verifiees par rapport a un hachage cryptographique qui couvre l'ensemble du fichier (par exemple, grace a un arbre de Merkel). STATX_ATTR_DAX (depuis Linux 5.8) Le fichier est dans l'etat DAX (acces direct au processeur). L'etat DAX essaie de minimiser les effets du cache du logiciel a la fois pour les mappages de memoire et les Entrees/Sorties de ce fichier. Cela necessite un systeme de fichiers qui a ete configure pour prendre en charge DAX. DAX suppose generalement que tous les acces se font a travers des instructions de chargement/stockage du processeur, ce qui peut minimiser la surcharge pour les petits acces, mais peut avoir un effet negatif 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 mappees en memoire peuvent etre effectuees avec des mappages directs en memoire qui contournent le cache de page du noyau. Alors que la propriete DAX a tendance a entrainer un transfert synchrone des donnees, cela ne procure pas les memes garanties que le drapeau O_SYNC (voir open(2)), ou les donnees et les metadonnees sont transferees ensemble. Un fichier DAX devrait accepter d'etre mappe avec le drapeau MAP_SYNC, ce qui permet a un programme d'utiliser les instructions de vidage du cache du processeur pour faire persister les operations de stockage du processeur sans un fsync(2) explicite. Voir mmap(2) pour plus d'informations. STATX_ATTR_MOUNT_ROOT (depuis Linux 5.8) Ce fichier est la racine d'un montage' VALEUR RENVOYEE En cas de succes, zero est renvoye. En cas d'erreur, -1 est renvoye et errno est definie pour preciser l'erreur. ERREURS EACCES La permission de parcours est refusee pour un des repertoires 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 reserve indique dans mask. (Actuellement, il y a un tel drapeau, designe par la constante STATX_RESERVED, avec la valeur 0x80000000U.) ELOOP Trop de liens symboliques rencontres 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 chaine vide et AT_EMPTY_PATH n'etait pas specifie dans flags. ENOMEM Pas assez de memoire (memoire noyau). ENOTDIR Un composant du prefixe du chemin nom_chemin n'est pas un repertoire ou nom_chemin est relatif, et le descripteur de fichier dirfd est associe a un fichier, pas a un repertoire. STANDARDS Linux. HISTORIQUE Linux 4.11, glibc 2.28. VOIR AUSSI 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) TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot et bubu Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.06 31 octobre 2023 statx(2)