stat(2)

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

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

SYNOPSIS
#include <sys/stat.h>

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

#include <fcntl.h>           /* Définition des constantes AT_* */
#include <sys/stat.h>

int fstatat(int dirfd, const char *restrict path,
         struct stat *restrict statbuf, int flags);

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

lstat() :
    /* Depuis la glibc 2.20 */ _DEFAULT_SOURCE
        || _XOPEN_SOURCE >= 500
        || /* Depuis la glibc 2.10 : */ _POSIX_C_SOURCE >= 200112L
        || /* Pour la glibc antérieure et égale à 2.19 */ _BSD_SOURCE

fstatat() :
    Depuis la glibc 2.10 :
        _POSIX_C_SOURCE >= 200809L
    avant la glibc 2.10 :
        _ATFILE_SOURCE

DESCRIPTION
These functions return information about a file, in the buffer pointed to by statbuf. No permissions are required on the file itself, but—in the case of stat(), fstatat(), and lstat()—execute (search) permission is required on all of the directories in path that lead to the file.

stat() and fstatat() retrieve information about the file pointed to by path; the differences for fstatat() are described below.

lstat() is identical to stat(), except that if path is a symbolic link, then it returns information about the link itself, not the file that the link refers to.

fstat() est identique à stat(), sauf que le fichier dont les renseignements sont à récupérer est référencé par le descripteur de fichier fd.

  La structure stat
Les trois fonctions renvoient une structure stat (consultez stat(3type)).

Note : pour des raisons de performance et de simplicité, différents champs dans la structure stat peuvent contenir des informations d'état à différents moments durant l'exécution de l'appel système. Par exemple, si st_mode ou st_uid sont modifiés par un autre processus en appelant chmod(2) ou chown(2), stat() peut renvoyer l'ancien st_mode en même temps que le nouveau st_uid ou l'ancien st_uid en même temps que le nouveau st_mode.

  fstatat()
L'appel système fstatat() est une interface plus générale pour accéder à des informations de fichier qui peut encore fournir exactement le comportement de chaque appel à stat(), lstat() et fstat().

If path is relative, then it is interpreted relative to the directory referred to by the file descriptor dirfd (rather than relative to the current working directory of the calling process, as is done by stat() and lstat() for a relative pathname).

If path is relative and dirfd is the special value AT_FDCWD, then path is interpreted relative to the current working directory of the calling process (like stat() and lstat()).

Si path est absolu, alors dirfd est ignoré.

L'argument attributs est soit 0, soit un OU binaire « | » avec les options suivantes :

AT_EMPTY_PATH (depuis Linux 2.6.39)
    If path 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, and the behavior of fstatat() is similar to that of fstat(). If dirfd is AT_FDCWD, the call operates on the current working directory. This flag is Linux-specific; define _GNU_SOURCE to obtain its definition.

AT_NO_AUTOMOUNT (depuis Linux 2.6.38)
    Don't automount the terminal ("basename") component of path. Since Linux 3.1 this flag is ignored. Since Linux 4.11 this flag is implied.

AT_SYMLINK_NOFOLLOW
    If path is a symbolic link, do not dereference it: instead return information about the link itself, like lstat(). (By default, fstatat() dereferences symbolic links, like stat().)

Consultez openat(2) pour une explication de la nécessité de fstatat().

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
    Search permission is denied for one of the directories in the path prefix of path. (See also path_resolution(7).)

EBADF
    Le descripteur de fichier fd est non valable.

EBADF
    (fstatat()) path is relative but dirfd is neither AT_FDCWD nor a valid file descriptor.

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

EINVAL
    (fstatat()) attributs contient un attribut non valable.

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

ENAMETOOLONG
    path est trop long.

ENOENT
    A component of path does not exist or is a dangling symbolic link.

ENOENT
    path is an empty string and AT_EMPTY_PATH was not specified in flags.

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

ENOTDIR
    A component of the path prefix of path is not a directory.

ENOTDIR
    (fstatat()) path is relative and dirfd is a file descriptor referring to a file other than a directory.

EOVERFLOW
    path or fd refers to a file whose size, inode number, or number of blocks cannot be represented in, respectively, the types off_t, ino_t, or blkcnt_t. This error can occur when, for example, an application compiled on a 32-bit platform without -D_FILE_OFFSET_BITS=64 calls stat() on a file whose size exceeds (1<<31)-1 bytes.

NORMES
POSIX.1-2024.

HISTORIQUE

stat()
fstat()
lstat()
    SVr4, 4.3BSD, POSIX.1-2001.

fstatat()
    POSIX.1-2008. Linux 2.6.16, glibc 2.4.

D'après POSIX.1-2001, lstat() sur un lien symbolique ne doit renvoyer des informations valables que dans le champ st_size et le type de fichier du champ st_mode de la structure stat. POSIX.1-2008 renforce la spécification, obligeant lstat() à renvoyer des informations valables dans tous les champs à part les bits de mode dans 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).

  Différences entre bibliothèque C et noyau
Avec le temps, l'augmentation de la taille de la structure stat a conduit à trois versions successives de stat() : sys_stat() (slot __NR_oldstat), sys_newstat() (slot __NR_stat) et sys_stat64() __NR_stat64) sur les plateformes 32 bits telles que i386. Les deux premières versions étaient déjà présentes dans Linux 1.0 (quoiqu'avec des noms différents), la dernière a été ajoutée dans Linux 2.4. La même remarque s'applique à fstat() et lstat().

Les versions internes du noyau de la structure stat traitées par les différentes versions étaient respectivement :

__old_kernel_stat
    La structure d'origine avec des champs plutôt étroits et pas de remplissage.

stat
    Un champ plus grand st_ino et le remplissage ont été ajoutés dans différentes parties de la structure pour autoriser un agrandissement futur.

stat64
    Un champ st_ino encore plus grand, des champs st_uid et st_gid plus grands pour s'adapter à l'extension à 32 bits des UID et GID dans Linux 2.4 et d'autres champs agrandis ainsi que plus de remplissage dans la structure. (Divers octets de remplissage étaient finalement consommés dans Linux 2.6 avec l'introduction d'ID de périphérique 32 bits et des composants en nanosecondes dans les champs d'horodatage.)

La fonction d'enveloppe stat() de la glibc dissimule ces détails aux applications invoquant la version la plus récente de l'appel système fourni par le noyau, et recompresse l'information renvoyée si nécessaire pour les binaires anciens.

Dans les systèmes modernes 64 bits, la vie est plus simple : il n'y a qu'un seul appel système stat() et le noyau s'occupe de la structure stat qui contient des champs d'une taille suffisante.

L'appel système sous-jacent employé par la fonction d'enveloppe fstatat() de la glibc s'appelle en fait fstatat64() ou, sur certaines architectures, newfstatat().

EXEMPLES
Le programme suivant appelle lstat() et affiche certains champs sélectionnés dans la structure stat renvoyée.

    #include <stdint.h>
    #include <stdio.h>
    #include <stdlib.h>
    #include <sys/stat.h>
    #include <sys/sysmacros.h>
    #include <time.h>

    int
    main(int argc, char *argv[])
    {
        struct stat sb;

        if (argc != 2) {
            fprintf(stderr, "Usage: %s <path>\n", argv[0]);
            exit(EXIT_FAILURE);
        }

        if (lstat(argv[1], &sb) == -1) {
            perror("lstat");
            exit(EXIT_FAILURE);
        }

        printf("ID of containing device:  [%x,%x]\n",
               major(sb.st_dev),
               minor(sb.st_dev));

        printf("File type:                ");

        switch (sb.st_mode & S_IFMT) {
        case S_IFBLK:  printf("block device\n");            break;
        case S_IFCHR:  printf("character device\n");        break;
        case S_IFDIR:  printf("directory\n");               break;
        case S_IFIFO:  printf("FIFO/pipe\n");               break;
        case S_IFLNK:  printf("symlink\n");                 break;
        case S_IFREG:  printf("regular file\n");            break;
        case S_IFSOCK: printf("socket\n");                  break;
        default:       printf("unknown?\n");                break;
        }

        printf("I-node number:            %ju\n", (uintmax_t) sb.st_ino);

        printf("Mode:                     %jo (octal)\n",
               (uintmax_t) sb.st_mode);

        printf("Link count:               %ju\n", (uintmax_t) sb.st_nlink);
        printf("Ownership:                UID=%ju   GID=%ju\n",
               (uintmax_t) sb.st_uid, (uintmax_t) sb.st_gid);

        printf("Preferred I/O block size: %jd bytes\n",
               (intmax_t) sb.st_blksize);
        printf("File size:                %jd bytes\n",
               (intmax_t) sb.st_size);
        printf("Blocks allocated:         %jd\n",
               (intmax_t) sb.st_blocks);

        printf("Last status change:       %s", ctime(&sb.st_ctime));
        printf("Last file access:         %s", ctime(&sb.st_atime));
        printf("Last file modification:   %s", ctime(&sb.st_mtime));

        exit(EXIT_SUCCESS);
    }

VOIR AUSSI
ls(1), stat(1), access(2), chmod(2), chown(2), readlink(2), statx(2), utime(2), stat(3type), 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 Jean-Pierre Giraud <jean-pierregiraud@neuf.fr>

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.