Provided by: manpages-fr-dev_3.17.1-1_all bug

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 (voir
   feature_test_macros(7)) :

       lstat() : _BSD_SOURCE || _XOPEN_SOURCE >= 500

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 i-nœ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  l’option  « noatime »  de
       mount(8)).

       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 en mode caractère ?

           S_ISBLK(m)  un périphérique en mode 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 blocs
           S_IFDIR    0040000   répertoire
           S_IFCHR    0020000   périphérique caractères
           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

       En  cas  de  réussite,  zéro est renvoyé, sinon -1 est renvoyé et errno
       contient le code d’erreur.

ERREURS

       EACCES La permission de parcours est refusée pour  un  des  répertoires
              contenu dans le chemin path. (Voir 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
              Nom de fichier trop long.

       ENOENT Un  composant  du  chemin  path n’existe pas, ou il s’agit d’une
              chaîne vide.

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

       ENOTDIR
              Un élément du chemin d’accès 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 à (2<<31)-1 bits.

CONFORMITÉ

       Ces appels système sont conformes à SVr4, BSD 4.3, POSIX.1-2001.

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

       POSIX  ne  décrit  pas  les  bits  S_IFMT,  S_IFSOCK, S_IFLNK, S_IFREG,
       S_IFBLK, S_IFDIR, S_IFCHR, S_IFIFO, S_ISVTX,  mais  réclame  d’utiliser
       les  macros  S_ISDIR(),  etc.  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   Fixer 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   Fixer 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éfini,  ou  bien
       st_atimensec si aucune de ces macros n’est définie. 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.

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

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_SUCCESS);
           }

           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.17 du projet man-pages
       Linux. Une description du projet et des instructions pour signaler  des
       anomalies       peuvent       être       trouvées      à      l’adresse
       http://www.kernel.org/doc/man-pages/.

TRADUCTION

       Cette page de manuel a été traduite  et  mise  à  jour  par  Christophe
       Blaess  <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis par
       Alain Portal <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et  mise  à
       disposition sur http://manpagesfr.free.fr/.

       Les mises à jour et corrections de la version présente dans Debian sont
       directement gérées par Julien Cristau <jcristau@debian.org> et l’équipe
       francophone de traduction de Debian.

       Veuillez   signaler   toute   erreur   de   traduction  en  écrivant  à
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

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