stat(2)

NAAM
stat, fstat, lstat, fstatat - verkrijg bestand status.

BIBLIOTHEEK
Standaard C bibliotheek (libc, -lc)

SAMENVATTING
#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>           /* Definitie van AT_* constanten */
#include <sys/stat.h>

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

    Feature Test Macro Requirements voor glibc (zie feature_test_macros(7)):

lstat():
    /* Vanaf glibc 2.20 */ _DEFAULT_SOURCE
        || _XOPEN_SOURCE >= 500
        || /* Vanaf glibc 2.10: */ _POSIX_C_SOURCE >= 200112L
        || /* glibc 2.19 en eerder */ _BSD_SOURCE

fstatat():
    Vanaf glibc 2.10:
        _POSIX_C_SOURCE >= 200809L
    Voor glibc 2.10:
        _ATFILE_SOURCE

BESCHRIJVING
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() is gelijk aan stat(), behalve dat het bestand van welk de informatie wordt opgevraagd wordt gespecificeerd door de bestandsindicator fd.

  De stat structuur
Al deze systeem aanroepen retourneren een stat structure (zie stat(3type)):

Opmerking: vanwege prestatie redenen en vanwege de eenvoud, mogen diverse velden in de stat structuur status informatie bevatten over verschillende momenten gedurende de uitvoer van de systeem aanroep. Bijvoorbeeld, als st_mode of st_uid werd veranderd door een ander proces door de aanroep van chmod(2) of chown(2), dan mag stat(2) de oude st_mode teruggeven, samen met de nieuwe st_uid, of de oude st_uid samen met de nieuwe st_mode.

  fstatat()
De fstatat() systeem aanroep is een meer algemeen interface voor het verkrijgen van bestandsinformatie dat nog steeds exact hetzelfde gedrag kan bieden van elk van stat(), lstat(), and 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()).

Als padnaam absoluut is, dan wordt mapbi genegeerd.

vlaggen kan ofwel 0 zijn, of kan een of meer van de volgende vlaggen ORed bevatten:

AT_EMPTY_PATH (vanaf 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 (vanaf 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().)

Zie openat(2) voor een uitleg over de noodzaak van fstatat().

EIND WAARDE
Bij succes wordt nul teruggegeven. Bij falen wordt -1 teruggegeven en wordt errno overeenkomstig gezet.

FOUTEN

EACCES
    Search permission is denied for one of the directories in the path prefix of path. (See also path_resolution(7).)

EBADF
    bi is niet een geldige open-voor-schrijven bestandindicator.

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

EFAULT
    Verkeerd adres.

EINVAL
    (fstatat()) Ongeldige vlag opgegeven in vlaggen.

ELOOP
    Teveel symbolische koppelingen werden tegengekomen bij het doorlopen van padnaam.

ENAMETOOLONG
    pad is te lang.

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
    Geheugen is op (kernel geheugen).

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.

STANDAARDEN
POSIX.1-2024.

HISTORIE

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

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

Volgens POSIX.1-2001, moet lstat() voor een symbolische koppeling geldige informatie retourneren in het st_size veld en het bestandstype van het st_mode veld van de stat structure. POSIX.1-2008 vernauwt deze specificatie door te vereisen dat lstat() geldige informatie moet retourneren in alle velden behalve de mode bits in st_mode.

Gebruik van de st_blocks en st_blksize velden is minder overdraagbaar. (Deze werden geïntroduceerd in BSD. De interpretatie verschilt tussen systemen, en mogelijk zelfs op een enkel systeem waar NFS koppelingen gebruikt worden.)

  C library/kernel verschillen
In de loop van de tijd hebben vergrotingen van de stat structure geleid tot drie opeenvolgende versies van stat(0: sys_stat() (slot __NR_oldstat), sys_newstat() (slot __NR_stat), en sys_stat64() (slot __NR_stat64) op 32-bit platformen zoals i386. De eerste twee versies waren al aanwezig in Linux 1.0 (hoewel met verschillende namen); de laatste werd toegevoegd in Linux 2.4. Vergelijkbare opmerkingen zijn van toepassing op fstat() en lstat().

De interne kernel versies van de stat structure die behandelt worden door de verschillende versies, zijn respectievelijk:

__old_kernel_stat
    De originele structure, met nogal kleine velden en zonder opvulling.

stat
    Een groter st_ino veld en opvulling toegevoegd aan verschillende delen van de structure om toekomstige uitbreidingen toe te staan.

stat64
    Een nog groter st_ino veld, grotere st_uid en st_gid velden om in de expansie van UID´s EN GID´s naar 32 bits door Linux-2.4 te voorzien, en verschillende andere vergrote velden en meer opvulling in de structure. (Diverse opvul bytes werden geconsumeerd in Linux 2.6, met de aankomst van 32-bit apparaat ID´s en nanoseconden componenten in de tijdstempel velden.)

De glibc stat() omwikkel functies verbergen deze details van de applicaties, door het aanroepen van de meest recente versie van de systeem aanroep die door de kernel beschikbaar wordt gesteld en het opnieuw inpakken van de verkregen informatie indien nodig voor oude toepassingen.

Op moderne 64-bit systemen is het leven eenvoudiger: daar bestaat een enkele stat() systeem aanroep en de kernel werkt met een stat structure die velden van voldoende grootte bevat.

De onderliggende systeem aanroep gebruikt door de glibc fstatat() omwikkel functie heet eigenlijk fstatat64() of op sommige architecturen newfstatat().

VOORBEELDEN
Het volgende programma roept lstat() aan en toont geselecteerde velden in de teruggegeven stat structure.

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

ZIE OOK
ls(1), stat(1), access(2), chmod(2), chown(2), readlink(2), statx(2), utime(2), stat(3type), capabilities(7), inode(7), symlink(7)

VERTALING
De Nederlandse vertaling van deze handleiding is geschreven door Jos Boersema <joshb@xs4all.nl>, Mario Blättermann <mario.blaettermann@gmail.com> en Luc Castermans <luc.castermans@gmail.com>

Deze vertaling is vrije documentatie; lees de GNU General Public License Version 3 (https://www.gnu.org/licenses/gpl-3.0.html) of later over de Copyright-voorwaarden. Er is geen AANSPRAKELIJKHEID.

Indien U fouten in de vertaling van deze handleiding zou vinden, stuur een e-mail naar debian-l10n-dutch@lists.debian.org.