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 *_Nullable restrict pathname, int flags, 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; /* Mask of bits indicating filled fields */ __u32 stx_blksize; /* Block size for filesystem I/O */ __u64 stx_attributes; /* Extra file attribute indicators */ __u32 stx_nlink; /* Number of hard links */ __u32 stx_uid; /* User ID of owner */ __u32 stx_gid; /* Group ID of owner */ __u16 stx_mode; /* File type and mode */ __u64 stx_ino; /* Inode number */ __u64 stx_size; /* Total size in bytes */ __u64 stx_blocks; /* Number of 512B blocks allocated */ __u64 stx_attributes_mask; /* Mask to show what's supported in stx_attributes */ /* The following fields are file timestamps */ struct statx_timestamp stx_atime; /* Last access */ struct statx_timestamp stx_btime; /* Creation */ struct statx_timestamp stx_ctime; /* Last status change */ struct statx_timestamp stx_mtime; /* Last modification */ /* If this file represents a device, then the next two fields contain the ID of the device */ __u32 stx_rdev_major; /* Major ID */ __u32 stx_rdev_minor; /* Minor ID */ /* The next two fields contain the ID of the device containing the filesystem where the file resides */ __u32 stx_dev_major; /* Major ID */ __u32 stx_dev_minor; /* Minor ID */ __u64 stx_mnt_id; /* Mount ID */ /* Direct I/O alignment restrictions */ __u32 stx_dio_mem_align; __u32 stx_dio_offset_align; __u64 stx_subvol; /* Subvolume identifier */ /* Direct I/O atomic write limits */ __u32 stx_atomic_write_unit_min; __u32 stx_atomic_write_unit_max; __u32 stx_atomic_write_segments_max; /* File offset alignment for direct I/O reads */ __u32 stx_dio_read_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 If pathname is an empty string (or NULL since Linux 6.11) and the AT_EMPTY_PATH flag is specified in flags (see below), then the target file is the one referred to by the file descriptor 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 If pathname is an empty string (or NULL since Linux 6.11), operate on the file referred to by dirfd (which may have been obtained using the open(2) O_PATH flag). In this case, dirfd can refer to any type of file, not just a directory. 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 Want stx_dio_mem_align and stx_dio_offset_align. (depuis Linux 6.1 ; prise en charge selon le systeme de fichiers) STATX_MNT_ID_UNIQUE Want unique stx_mnt_id (since Linux 6.8) STATX_SUBVOL Want stx_subvol (since Linux 6.10; support varies by filesystem) STATX_WRITE_ATOMIC Want stx_atomic_write_unit_min, stx_atomic_write_unit_max, and stx_atomic_write_segments_max. (since Linux 6.11; support varies by filesystem) STATX_DIO_READ_ALIGN Want stx_dio_read_offset_align. (since Linux 6.14; support varies by filesystem) 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 stx_dev_minor Le peripherique sur lequel reside ce fichier (inoeud). stx_rdev_major stx_rdev_minor Le peripherique que ce fichier (inoeud) represente si le fichier est de type peripherique bloc ou caractere. stx_mnt_id If using STATX_MNT_ID, this is the mount ID of the mount containing the file. This is the same number reported by name_to_handle_at(2) and corresponds to the number in the first field in one of the records in /proc/self/mountinfo. If using STATX_MNT_ID_UNIQUE, this is the unique mount ID of the mount containing the file. This is the number reported by listmount(2) and is the ID used to query the mount with statmount(2). It is guaranteed to not be reused while the system is running. 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. stx_dio_read_offset_align The alignment (in bytes) required for file offsets and I/O segment lengths for direct I/O reads (O_DIRECT) on this file. If zero, the limit in stx_dio_offset_align applies for reads as well. If non-zero, this value must be smaller than or equal to stx_dio_offset_align which must be provided by the file system if requested by the application. The memory alignment in stx_dio_mem_align is not affected by this value. STATX_DIO_READ_ALIGN (stx_dio_offset_align) is supported by xfs on regular files since Linux 6.14. stx_subvol Subvolume number of the current file. Subvolumes are fancy directories, i.e. they form a tree structure that may be walked recursively. Support varies by filesystem; it is supported by bcachefs and btrfs since Linux 6.10. stx_atomic_write_unit_min stx_atomic_write_unit_max The minimum and maximum sizes (in bytes) supported for direct I/O (O_DIRECT) on the file to be written with torn-write protection. These values are each guaranteed to be a power-of-2. STATX_WRITE_ATOMIC (stx_atomic_write_unit_min, stx_atomic_write_unit_max, and stx_atomic_write_segments_max) is supported on block devices since Linux 6.11. The support on regular files varies by filesystem; it is supported by xfs and ext4 since Linux 6.13. stx_atomic_write_segments_max The maximum number of elements in an array of vectors for a write with torn-write protection enabled. See RWF_ATOMIC flag for pwritev2(2). 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_WRITE_ATOMIC (since Linux 6.11) The file supports torn-write protection. 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 pathname or statxbuf points to a location outside the process's accessible address space or is NULL (except since Linux 6.11 if AT_EMPTY_PATH is specified in flags, pathname is allowed to be NULL). 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.12 11 janvier 2025 statx(2)