statx(2)

NOM
statx - Afficher l'état d'un fichier (étendu)

BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)

SYNOPSIS
#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 *_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 pointé par statxbuff. Le tampon renvoyé 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 réservé et le remplissage sont ommis.)

  Invoking statx():
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
    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 ê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
    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 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 | Want stx_dio_mem_align and stx_dio_offset_align.
 | (depuis Linux 6.1 ; prise en charge selon le système 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 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.

  Information renvoyée
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
stx_dev_minor
    Le périphérique sur lequel réside ce fichier (inœud).

stx_rdev_major
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
    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 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.

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 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_WRITE_ATOMIC (since Linux 6.11)
    The file supports torn-write protection.

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.

STATX_ATTR_MOUNT_ROOT (depuis Linux 5.8)
    Ce fichier est la racine d'un montage'

VALEUR RENVOYÉE
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.

ERREURS

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
    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 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.

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 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 (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.