STAT(2)

NOM
stat, fstat, lstat - Obtenir l'état d'un fichier (file status)

SYNOPSIS
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>

int stat(const char *path, struct stat *buf);
int fstat(int fd, struct stat *buf);
int lstat(const char *path, struct stat *buf);

Exigences de macros de test de fonctionnalités pour la glibc (consultez feature_test_macros(7)) :

lstat() :
    _BSD_SOURCE || _XOPEN_SOURCE >= 500 || _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
    || /* Depuis la glibc 2.10 : */ _POSIX_C_SOURCE >= 200112L

DESCRIPTION

Ces fonctions renvoient des informations à propos du fichier indiqué. Vous n'avez besoin d'aucun droit d'accès au fichier pour obtenir les informations, mais vous devez — dans le cas de stat() et lstat() — avoir le droit de parcours de tous les répertoires mentionnés dans le chemin menant au fichier.

stat() récupère l'état du fichier pointé par path et remplit le tampon buf. lstat() est identique à stat(), sauf que dans le cas où path est un lien symbolique, il donne l'état du lien lui-même plutôt que celui du fichier visé. fstat() est identique à stat(), sauf que le fichier dont l'état est donné est celui référencé par le descripteur de fichier fd.

Les trois fonctions retournent une structure stat contenant les champs suivants :

struct stat {
    dev_t     st_dev;      /* Périphérique                    */
    ino_t     st_ino;      /* Numéro inœud                    */
    mode_t    st_mode;     /* Protection                      */
    nlink_t   st_nlink;    /* Nb liens matériels              */
    uid_t     st_uid;      /* UID propriétaire                */
    gid_t     st_gid;      /* GID propriétaire                */
    dev_t     st_rdev;     /* Type périphérique               */
    off_t     st_size;     /* Taille totale en octets         */
    blksize_t st_blksize;  /* Taille de bloc pour E/S         */
    blkcnt_t  st_blocks;   /* Nombre de blocs de 512B alloués */
    time_t    st_atime;    /* Heure dernier accès             */
    time_t    st_mtime;    /* Heure dernière modification     */
    time_t    st_ctime;    /* Heure dernier changement état   */
};

Le champ st_dev décrit le périphérique sur lequel ce fichier réside. Les macros major(3) et minor(3) peuvent être utiles pour décomposer l'identifiant de périphérique de ce champ. Le champ st_rdev indique le périphérique que ce fichier (inœud) représente. Le champ st_size indique 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 de la chaîne représentant le chemin d'accès qu'il vise, sans le caractère NUL final. Le champ st_blocks indique le nombre de blocs de 512 octets alloués au fichier. Cette valeur peut être inférieure à st_size/512 si le fichier a des trous. Le champ st_blksize donne la taille de bloc « préférée » pour des entrées-sorties efficaces. Des écritures par blocs plus petits peuvent entraîner un cycle lecture/modification/réécriture inefficace.

Tous les systèmes de fichiers de Linux n'implémentent pas tous les champs liés à la date. Certains systèmes de fichiers autorisent le montage de telle manière que les accès à des fichiers et/ou répertoires ne modifient pas le champ st_atime (voir les options noatime, nodiratime et relatime de mount(8) ainsi que les informations correspondante dans mount(2)). De plus, st_atime n'est pas mis à jour si un fichier est ouvert avec l'option O_NOATIME ; consultez open(2). Le champ st_atime est modifié par les accès au fichier, par exemple avec execve(2), mknod(2), pipe(2), utime(2) et read(2) (d'au moins un octet). D'autres routines, comme mmap(2), peuvent ou non mettre à jour ce champ st_atime. Le champ st_mtime est modifié par des changements sur le fichier lui-même, c'est-à-dire mknod(2), truncate(2), utime(2) et write(2) (d'au moins un octet). D'autre part, le champ st_mtime d'un répertoire est modifié lors de la création ou la suppression de fichiers en son sein. Le champ st_mtime n'est pas mis à jour lors de modification de propriétaire, groupe, mode ou nombre de liens physiques. Le champ st_ctime est modifié lors d'une écriture ou une modification de données concernant l'inœud (propriétaire, groupe, mode, etc.).

Les macros POSIX suivantes sont fournies pour vérifier le type de fichier (dans le champ st_mode) :

    S_ISREG(m)
        un fichier ordinaire ?

    S_ISDIR(m)
        un répertoire ?

    S_ISCHR(m)
        un périphérique caractère ?

    S_ISBLK(m)
        un périphérique bloc ?

    S_ISFIFO(m)
        FIFO (tube nommé) ?

    S_ISLNK(m)
        un lien symbolique ? (Pas dans POSIX.1-1996).

    S_ISSOCK(m)
        une socket ? (Pas dans POSIX.1-1996).

Les attributs suivants correspondent au champ st_mode :
S_IFMT | 0170000 | masque du type de fichier
S_IFSOCK | 0140000 | socket
S_IFLNK | 0120000 | lien symbolique
S_IFREG | 0100000 | fichier ordinaire
S_IFBLK | 0060000 | périphérique bloc
S_IFDIR | 0040000 | répertoire
S_IFCHR | 0020000 | périphérique caractère
S_IFIFO | 0010000 | fifo
S_ISUID | 0004000 | bit Set-UID
S_ISGID | 0002000 | bit Set-Gid (voir ci-dessous)
S_ISVTX | 0001000 | bit « sticky » (voir ci-dessous)
S_IRWXU | 00700 | lecture/écriture/exécution du propriétaire
S_IRUSR | 00400 | le propriétaire a le droit de lecture
S_IWUSR | 00200 | le propriétaire a le droit d'écriture
S_IXUSR | 00100 | le propriétaire a le droit d'exécution
S_IRWXG | 00070 | lecture/écriture/exécution du groupe
S_IRGRP | 00040 | le groupe a le droit de lecture
S_IWGRP | 00020 | le groupe a le droit d'écriture
S_IXGRP | 00010 | le groupe a le droit d'exécution
S_IRWXO | 00007 | lecture/écriture/exécution des autres
S_IROTH | 00004 | les autres ont le droit de lecture
S_IWOTH | 00002 | les autres ont le droit d'écriture
S_IXOTH | 00001 | les autres ont le droit d'exécution

Le bit Set-GID (S_ISGID) a plusieurs utilisations particulières : pour un répertoire, il indique que la sémantique BSD doit être appliquée en son sein, c'est-à-dire que les fichiers qui y sont créés héritent leur GID du répertoire et non pas du GID effectif du processus créateur, et les sous-répertoires auront automatiquement le bit S_ISGID actif. Pour les fichiers qui n'ont pas d'autorisation d'exécution pour le groupe (S_IXGRP non actif), ce bit indique qu'un verrouillage strict est en vigueur sur ce fichier.

Le bit « sticky » (S_ISVTX) sur un répertoire indique que les fichiers qui s'y trouvent ne peuvent être renommés ou effacés que par leur propriétaire, par le propriétaire du répertoire ou par un processus privilégié.

VALEUR RENVOYÉE
S'il réussit, cet appel système renvoie 0. S'il échoue, il renvoie -1 et remplit errno en conséquence.

ERREURS

EACCES
    La permission de parcours est refusée pour un des répertoires contenu dans le chemin path. (Consultez aussi path_resolution(7).)

EBADF
    fd est un mauvais descripteur.

EFAULT
    Un pointeur se trouve en dehors de l'espace d'adressage.

ELOOP
    Trop de liens symboliques rencontrés dans le chemin d'accès.

ENAMETOOLONG
    path est trop long.

ENOENT
    Un composant du chemin path n'existe pas, ou path est une chaîne vide.

ENOMEM
    Pas assez de mémoire (mémoire noyau).

ENOTDIR
    Un élément du préfixe du chemin path n'est pas un répertoire.

EOVERFLOW
    (stat()) path se réfère à un fichier dont la taille ne peut pas être représentée avec le type off_t. Ceci peut arriver quand une application compilée sans l'option -D_FILE_OFFSET_BITS=64 sur une plate-forme 32 bits appelle stat() pour un fichier dont la taille est supérieure à (1<<31)-1 bits.

CONFORMITÉ
Ces appels système sont conformes à SVr4, BSD 4.3, POSIX.1-2001. D'après POSIX.1-2001, lstat() sur un lien symbolique ne doit renvoyer des informations valables que dans le champ st_size et pour le composant de type de fichier du champ st_mode de la structure stat. POSIX.-2008 renforce la spécification, obligeant lstat() à renvoyer des informations valables dans tous les champs à part les bits de droit de st_mode. L'utilisation des champs st_blocks et st_blksize risque d'être moins portable (ils ont été introduits dans BSD. Leur interprétation change suivant les systèmes, voire sur un même système s'il y a des montages NFS). Si vous avez besoin de connaitre la définition des types blkcnt_t ou blksize_t de <sys/stat.h>, alors définissez _XOPEN_SOURCE avec une valeur supérieure ou égale à 500 (avant d'inclure tout en-tête).

POSIX.1-1990 ne décrivait pas les constantes S_IFMT, S_IFSOCK, S_IFLNK, S_IFREG, S_IFBLK, S_IFDIR, S_IFCHR, S_IFIFO, S_ISVTX, mais réclamait d'utiliser les macros S_ISDIR(), etc. Les constantes S_IF*() sont présentes dans POSIX.1-2011 et versions suivantes. Les macros S_ISLNK() et S_ISSOCK() ne se trouvent pas dans POSIX.1-1996 mais sont présentes dans POSIX.1-2001. La première vient de SVID 4, la seconde de SUSv2.

UNIX V7 (et les systèmes suivants) propose S_IREAD, S_IWRITE, S_IEXEC, là où POSIX préfère leurs synonymes S_IRUSR, S_IWUSR, S_IXUSR.

  Autres systèmes
Voici quelques valeurs qui ont été (ou sont) utilisées sur d'autres systèmes
hex | nom | ls | octal | description
f000 | S_IFMT |  | 170000 | Masque du type de fichier
0000 |  |  | 000000 | inœud hors-service (SCO) ; type inconnu
 |  |  |  | (BSD) ; SVID-v2 et XPG2 ont 0 et
 |  |  |  | 0100000 pour « fichier ordinaire »
1000 | S_IFIFO | p| | 010000 | fifo (tube nommé)
2000 | S_IFCHR | c | 020000 | fichier spécial caractère (V7)
3000 | S_IFMPC |  | 030000 | fichier spécial caractère multiplexé
 |  |  |  | (V7)
4000 | S_IFDIR | d/ | 040000 | répertoire (V7)
5000 | S_IFNAM |  | 050000 | fichier spécial nommé XENIX avec deux
 |  |  |  | sous-types distingués par
 |  |  |  | st_rdev valant 1 ou 2
0001 | S_INSEM | s | 000001 | sous-type sémaphore de IFNAM XENIX
0002 | S_INSHD | m | 000002 | sous-type données partagées de IFNAM
 |  |  |  | XENIX
6000 | S_IFBLK | b | 060000 | fichier spécial bloc (V7)
7000 | S_IFMPB |  | 070000 | fichier spécial bloc multiplexé (V7)
8000 | S_IFREG | - | 100000 | fichier normal (V7)
9000 | S_IFCMP |  | 110000 | compressé VxFS
9000 | S_IFNWK | n | 110000 | fichier spécial réseau (HP-UX)
a000 | S_IFLNK | l@ | 120000 | lien symbolique (BSD)
b000 | S_IFSHAD |  | 130000 | Fichier shadow Solaris pour l'ACL
 |  |  |  | (invisible depuis l'espace utilisateur)
c000 | S_IFSOCK | s= | 140000 | socket (BSD; aussi "S_IFSOC" sur VxFS)
d000 | S_IFDOOR | D> | 150000 | Solaris door
e000 | S_IFWHT | w% | 160000 | BSD whiteout (non utilisé pour les
 |  |  |  | inœuds)
0200 | S_ISVTX |  | 001000 | « sticky bit »: garder en mémoire
 |  |  |  | après exécution (V7)
 |  |  |  | réservé (SVID-v2)
 |  |  |  | non-répertoires : ne pas swapper le
 |  |  |  | fichier (SunOS)
 |  |  |  | répertoires : attribut de restrictions
 |  |  |  | d'effacement (SVID-v4.2)
0400 | S_ISGID |  | 002000 | Définir le GID à l'exécution (V7)
 |  |  |  | pour les répertoires : sémantique BSD
 |  |  |  | pour la propagation du GID
0400 | S_ENFMT |  | 002000 | Verrouillage strict System V
 |  |  |  | (partagé avec S_ISGID)
0800 | S_ISUID |  | 004000 | Définir l'UID à l'exécution (V7)
0800 | S_CDF |  | 004000 | Le répertoire est un fichier
 |  |  |  | dépendant du contexte (HP-UX)
Une commande sticky est apparue dans la version 32V d'AT&T UNIX.

NOTES
Depuis le noyau 2.5.48, la structure stat propose une résolution d'une nanoseconde pour les trois champs d'heure. La glibc montre le composant en nanosecondes de chaque champ en utilisant des noms de la forme st_atim.tv_nsec si _BSD_SOURCE ou _SVID_SOURCE est définie. Ces champs sont définis dans POSIX.1-2008 et, à partir de la version 2.12, la glibc expose aussi ces noms de champs si _POSIX_C_SOURCE est définie avec une valeur supérieure ou égale à 200809L ou si _XOPEN_SOURCE est définie avec une valeur supérieure ou égale à 700. Si aucune de ces macros ne sont définies, alors les valeurs en nanosecondes sont exposées avec des noms de la forme st_atimensec. Sur les systèmes de fichiers qui ne gèrent pas les résolutions inférieures à la seconde, ces champs prennent la valeur 0. Sous Linux, lstat() ne provoque généralement pas d'action de l'« automonteur », tandis que stat() le fera (mais consultez fstatat(2)). Pour la plupart des fichiers sous /proc, stat() ne renvoie pas la taille du fichier dans le champ st_size. La valeur 0 est placée dans ce champ.

  Interface noyau sous-jacente
Avec le temps, l'augmentation de la taille de la structure stat a conduit à 3 versions successives de stat() : sys_stat() (entrée __NR_oldstat), sys_newstat() (entrée __NR_stat) et sys_stat64() (nouveauté du noyau 2.4 ; entrée __NR_stat64). La fonction stat() fournie par la glibc cache ces détails aux applications, en appelant la version la plus récente de l'appel système fournie par le noyau et en réorganisant si nécessaire les informations renvoyées pour les anciens binaires. La même remarque s'applique à fstat() et lstat().

EXEMPLE
Le programme suivant appelle stat() et affiche certains champs sélectionnés dans la structure stat renvoyée.
#include <sys/types.h>
#include <sys/stat.h>
#include <time.h>
#include <stdio.h>
#include <stdlib.h>
int
main(int argc, char *argv[])
{
    struct stat sb;
    if (argc != 2) {
        fprintf(stderr, "Usage: %s <pathname>\n", argv[0]);
        exit(EXIT_FAILURE);
    }
    if (stat(argv[1], &sb) == -1) {
        perror("stat");
        exit(EXIT_FAILURE);
    }
    printf("Type de fichier :                  ");
    switch (sb.st_mode & S_IFMT) {
    case S_IFBLK:  printf("périphérique bloc\n");       break;
    case S_IFCHR:  printf("périphérique caractère\n");  break;
    case S_IFDIR:  printf("répertoire\n");              break;
    case S_IFIFO:  printf("FIFO/tube\n");               break;
    case S_IFLNK:  printf("lien symbolique\n");         break;
    case S_IFREG:  printf("fichier ordinaire\n");       break;
    case S_IFSOCK: printf("socket\n");                  break;
    default:       printf("inconnu ?\n");               break;
    }
    printf("Numéro d'inœud :                   %ld\n", (long) sb.st_ino);
    printf("Mode :                             %lo (octal)\n",
            (unsigned long) sb.st_mode);
    printf("Nombre de liens :                  %ld\n", (long) sb.st_nlink);
    printf("Propriétaires :                    UID=%ld   GID=%ld\n",
            (long) sb.st_uid, (long) sb.st_gid);
    printf("Taille de bloc d'E/S :             %ld octets\n",
            (long) sb.st_blksize);
    printf("Taille du fichier :                %lld octets\n",
            (long long) sb.st_size);
    printf("Blocs alloués :                    %lld\n",
            (long long) sb.st_blocks);
    printf("Dernier changement d'état :        %s", ctime(&sb.st_ctime));
    printf("Dernier accès au fichier :         %s", ctime(&sb.st_atime));
    printf("Dernière modification du fichier : %s", ctime(&sb.st_mtime));
    exit(EXIT_SUCCESS);
}

VOIR AUSSI
access(2), chmod(2), chown(2), fstatat(2), readlink(2), utime(2), capabilities(7), symlink(7)

COLOPHON
Cette page fait partie de la publication 3.40 du projet man-pages Linux. Une description du projet et des instructions pour signaler des anomalies peuvent être trouvées à l'adresse <URL:http://www.kernel.org/doc/man-pages/>.

TRADUCTION
Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a <URL:http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet perkamon <URL:http://perkamon.alioth.debian.org/>.

Christophe Blaess <URL:http://www.blaess.fr/christophe/> (1996-2003), Alain Portal <URL:http://manpagesfr.free.fr/> (2003-2006). Julien Cristau et l'équipe francophone de traduction de Debian (2006-2009).

Veuillez signaler toute erreur de traduction en écrivant à <perkamon-fr@traduc.org>.

Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la commande « LC_ALL=C man <section> <page_de_man> ».