NOM
stat, stat64, fstat, fstat64, lstat, lstat64 - 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);
int stat64(const char *path, struct stat64 *buf);
int fstat64(int fd, struct stat64 *buf);
int lstat64(const char *path, struct stat64 *buf);
En environnement 32 bits, stat64, fstat64 et lstat64 opèrent sur les
fichiers de taille supérieure à 2 Go (moins un octet). Se référer à open(2)
(O_LARGEFILE) ou au standard LFS.
Exigences de macros de test de fonctionnalités pour la glibc (voir
feature_test_macros(7)) :
lstat() : _BSD_SOURCE || _XOPEN_SOURCE >= 500
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 */
};
Concernant les fonctions stat64, fstat64, lstat64 (théoriquement) :
struct stat64 {
dev_t st_dev; /* Périphérique */
ino64_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 */
off64_t st_size; /* Taille totale en octets */
blksize_t st_blksize; /* Taille de bloc pour E/S */
blkcnt64_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 ; voir 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 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 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 à (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() 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.23 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/.
Révisé pour ce site par l'équipe man-linux-magique.net (Octobre 2010).
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> ».