STAT

Section: Manuel du programmeur Linux (2)
Updated: 18 juillet 2003
Index


NOM
SYNOPSIS
DESCRIPTION
VALEUR RENVOYÉE
ERREURS
CONFORMITÉ
AUTRES SYSTÈMES
VOIR AUSSI
TRADUCTION

NOM

stat, fstat, lstat - Obtenir le statut d'un fichier (file status).

SYNOPSIS

#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
int stat(const char *file_name, struct stat *buf);
int fstat(int filedes, struct stat *buf);
int lstat(const char *file_name, struct stat *buf);

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 avoir le droit de parcours de tous les répertoires mentionnés dans le chemin menant au fichier.
stat récupère le statut du fichier pointé par file_name et remplit le buffer buf.
lstat est identique à stat, sauf que dans le cas d'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 ouvert est pointé par le descripteur filedes, obtenu avec open(2).

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-noeud              */
    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 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    */
};

Le champ st_size indique la taille du fichier (s'il s'agit d'un fichier régulier 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.
La valeur st_blocks donne la taille du fichier en blocs de 512 octets. (Cette valeur peut être plus petite que st_size/512 par exemple si le fichier contient des trous). La valeur st_blksize indique la taille de bloc "préférée" pour les entrées/sorties du système (l'écriture dans un fichier par petits morceaux peut induire de nombreuses étapes lecture-modification-écriture peu efficaces).
Les systèmes de fichiers de Linux n'implémentent pas tous les champs "time". Certains systèmes de fichiers autorise le montage de telle manière que les accès 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, c'est à dire avec exec(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 généralement 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, une lecture, ou une modification de données concernant l'i-noeud (propriétaire, groupe, mode, etc...)
Les macros POSIX suivantes sont fournies pour vérifier le type de fichier :
S_ISREG(m)
un fichier régulier ?
S_ISDIR(m)
un répertoire ?
S_ISCHR(m)
un péripherique en mode caractère ?
S_ISBLK(m)
un périphérique en mode bloc ?
S_ISFIFO(m)
une FIFO ?
S_ISLNK(m)
est-ce 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_IFMT00170000masque du type de fichier
S_IFSOCK0140000socket
S_IFLNK0120000lien symbolique
S_IFREG0100000fichier régulier
S_IFBLK0060000périphérique blocs
S_IFDIR0040000répertoire
S_IFCHR0020000périphérique caractères
S_IFIFO0010000fifo
S_ISUID0004000bit Set-UID
S_ISGID0002000bit Set-Gid
S_ISVTX0001000bit "sticky"
S_IRWXU00700lecture/écriture/exécution du propriétaire
S_IRUSR00400le propriétaire a le droit de lecture
S_IWUSR00200le propriétaire a le droit d'écriture
S_IXUSR00100le propriétaire a le droit d'exécution
S_IRWXG00070lecture/écriture/exécution du groupe
S_IRGRP00040le groupe a le droit de lecture
S_IWGRP00020le groupe a le droit d'écriture
S_IXGRP00010le groupe a le droit d'exécution
S_IRWXO00007lecture/écriture/exécution des autres
S_IROTH00004les autres ont le droit de lecture
S_IWOTH00002les autres ont le droit d'écriture
S_IXOTH00001les 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épertoire 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 root.

VALEUR RENVOYÉE

Ces fonctions retournent zéro si elles réussissent. En cas d'echec -1 est renvoyé, et errno contient le code d'erreur.

ERREURS

EBADF
filedes est un mauvais descripteur.
ENOENT
Un composant de file_name n'existe pas, ou il s'agit d'une chaine vide.
ENOTDIR
Un composant du chemin d'accès n'est pas un répertoire.
ELOOP
Trop de liens symboliques rencontrés dans le chemin d'accès.
EFAULT
Un pointeur se trouve en dehors de l'espace d'adressage.
EACCES
Autorisation refusée.
ENOMEM
Pas assez de mémoire pour le noyau.
ENAMETOOLONG
Nom de fichier trop long

CONFORMITÉ

Les appels stat et fstat sont conformes aux versions SVr4, POSIX, X/OPEN, BSD 4.3. L'appel lstat est conforme aux versions BSD 4.3 et SVr4. SVr4 mentionne des conditions d'erreurs supplémentaires pour fstat EINTR, ENOLINK, et EOVERFLOW. Pour stat et lstat SVr4 indique les conditions supplémentaires EACCES, EINTR, EMULTIHOP, ENOLINK, et EOVERLOW. L'utilisation des champs st_blocks et st_blksize risque d'être moins portable. Ils ont été introduit dans BSD, et ne sont pas mentionnée dans POSIX. 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_ISLKNK et S_ISSOCK ne se trouvent pas dans POSI.1-1996 mais seront présentes dans le prochain standard POSIX. La première vient de SVID 4v2, 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
hexnomlsoctaldescription
f000S_IFMT170000Masque du type de fichier
0000000000SCO out-of-service inode, BSD unknown type
SVID-v2 and XPG2 have both 0 and 0100000 for ordinary file
1000S_IFIFOp|010000fifo (tube nommé)
2000S_IFCHRc020000fichier spécial caractère (V7)
3000S_IFMPC030000fichier spécial caractère multiplexé (V7)
4000S_IFDIRd/040000répertoire (V7)
5000S_IFNAM050000fichier spécial nommé XENIX avec deux
sous-types distingués par st_rdev valant 1 ou 2:
0001S_INSEMs000001sous-type sémaphore de IFNAM XENIX
0002S_INSHDm000002sous-type données partagées de IFNAM XENIX
6000S_IFBLKb060000fichier spécial bloc (V7)
7000S_IFMPB070000fichier spécial bloc multiplexé (V7)
8000S_IFREG-100000fichier normal (V7)
9000S_IFCMP110000compressé VxFS
9000S_IFNWKn110000fichier spécial réseau (HP-UX)
a000S_IFLNKl@120000lien symbolique (BSD)
b000S_IFSHAD130000Fichier shadow Solaris pour l'ACL (invisible)
c000S_IFSOCKs=140000socket (BSD; aussi "S_IFSOC" sur VxFS)
d000S_IFDOORD>150000Solaris door
e000S_IFWHTw%160000BSD whiteout (non utilisé pour les inoeuds)

 

0200S_ISVTX001000`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 : restrictions d'effacement (SVID-v4.2)
0400S_ISGID002000Utiliser l'ID du groupe à l'exécution (V7)
répertoires : sémantique BSD propageant le GID
0400S_ENFMT002000Verrouillage strict Système V (partage S_ISGID)
0800S_ISUID004000Utiliser l'ID utilisateur à l'exécution (V7)
0800S_CD004000Fichier répertoire dépendant du contexte (HP-UX)
Une commande sticky est apparue dans la version 32V d'AT&T UNIX.

VOIR AUSSI

chmod(2), chown(2), readlink(2), utime(2)

TRADUCTION

Christophe Blaess, 1996-2003.