stat, fstat, lstat, fstatat

#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>

int stat(const char *Pfadname, struct stat *Puffer);
int fstat(int fd, struct stat *Puffer);
int lstat(const char *Pfadname, struct stat *Puffer);

#include <fcntl.h>           /* Definition der AT_*-Konstanten */
#include <sys/stat.h>

int fstatat(int dirfd, const char *Pfadname, struct stat *Puffer,
            int Schalter);

Mit Glibc erforderliche Makros (siehe feature_test_macros(7)):

lstat():

fstatat():

Diese Funktionen geben Informationen über eine Datei im Puffer zurück, auf den buf zeigt. Dazu werden keinerlei Rechte an der angegebenen Datei benötigt, aber —im Falle von stat(), fstatat() und lstat()— müssen alle Verzeichnisse im Pfadnamen, der zu der Datei führt, durchsucht werden dürfen.

stat() und fstatat() liefern die Informationen zu der in Pfadname angegebenen Datei und übergibt diese an fstatat(), wie nachfolgend beschrieben.

lstat() ist ähnlich stat(), nur dass falls Pfadname ein symbolischer Link ist, Informationen zum Link zurückgegeben werden und nicht zur Datei, auf die der Link zeigt.

fstat ist ähnlich stat, außer dass die Datei, zu der Informationen ermittelt werden sollen, durch den Dateideskriptor fd angegeben wird.

Alle diese Systemaufrufe geben eine Struktur vom Typ stat zurück, die folgendermaßen aufgebaut ist:

struct stat {
    dev_t         st_dev;      /* Gerät */
    ino_t         st_ino;      /* INode */
    mode_t        st_mode;     /* Zugriffsrechte */
    nlink_t       st_nlink;    /* Anzahl harter Links */
    uid_t         st_uid;      /* UID des Besitzers */
    gid_t         st_gid;      /* GID des Besitzers */
    dev_t         st_rdev;     /* Typ (wenn INode-Gerät) */
    off_t         st_size;     /* Größe in Bytes*/
    blksize_t     st_blksize;  /* Blockgröße für Dateisystem-E/A */
    blkcnt_t      st_blocks;   /* Anzahl der zugewiesenen 512B-Blöcke */
   /* Seit Linux 2.6 unterstützt der Kernel Nanosekundengenauigkeit
      für die folgenden Zeitstempelfelder.
      Für Details vor Linux 2.6 lesen Sie ANMERKUNGEN. */
    struct timespec st_atim;  /* Zeit des letzten Zugriffs */
    struct timespec st_mtim;  /* Zeit der letzten Veränderung*/
    struct timespec st_ctim;  /* Zeit der letzten Statusänderung*/
#define st_atime st_atim.tv_sec      /* Rückwärtskompatibilität */
#define st_mtime st_mtim.tv_sec
#define st_ctime st_ctim.tv_sec
};

Hinweis: Die Reihenfolge der Felder in der stat-Struktur ist in den verschiedenen Architekturen nicht gleich. Außerdem zeigt die oben genannte Definition nicht die Auffüll-Bytes, die in verschiedenen Architekturen zwischen einigen Feldern vorhanden sind. Im Quellcode von Glibc und Kernel finden Sie bei Bedarf Details hierzu.

Note: For performance and simplicity reasons, different fields in the stat structure may contain state information from different moments during the execution of the system call. For example, if st_mode or st_uid is changed by another process by calling chmod(2) or chown(2), stat() might return the old st_mode together with the new st_uid, or the old st_uid together with the new st_mode.

Das Feld st_dev beschreibt das Gerät, auf dem sich die Datei befindet. (Die Makros major(3) und minor(3) können zum Zerlegen der Geräte-ID in diesem Feld nützlich sein.)

Das Feld st_rdev beschreibt das Geräte, das diese Datei (Inode) repräsentiert.

Das Feld st_size zeigt die Größe der Datei (falls es sich um eine reguläre Datei oder einen symbolischen Link handelt) in Bytes an. Die Größe des symbolischen Links ist die Länge des enthaltenen Pfadnamens ohne abschließendes Nullbyte.

Das Feld st_blocks gibt die Anzahl der Blöcke, die der Datei zugewiesen sind, in 512-Byte-Einheiten an. Dies kann kleiner als st_size/512 sein, wenn die Datei Löcher enthält.

Das Feld st_blksize gibt die »bevorzugte« Blockgröße für effiziente E/A-Operationen des Dateisystems an (Schreiben in eine Datei in kleineren Teilen kann ineffizientes Lesen-Ändern-Schreiben verursachen).

Nicht alle der Linux-Dateisysteme implementieren auch alle Zeitfelder. Einige Dateisystemtypen erlauben das Einhängen in einer Weise, dass Datei- und/oder Verzeichniszugriffe keine Aktualisierung des Feldes st_atime bewirken (siehe noatime, nodiratime und relatime in mount(8) sowie diesbezügliche Informationen in mount(2)). Außerdem wird st_atime nicht aktualisiert, wenn eine Datei mit O_NOATIME geöffnet wird; siehe open(2).

Das Feld st_atime wird durch Dateizugriffe geändert, zum Beispiel durch execve(2), mknod(2), pipe(2), utime(2) und read(2) (von mehr als 0 Bytes). Andere Routinen, wie mmap(2), können st_atime ändern, müssen dies aber nicht.

Das Feld st_mtime verändert sich beim Einsatz von dateimodifizierenden Operationen, z.B. durch mknod(2), truncate(2), utime(2) und write(2) (von mehr als null Bytes). Außerdem wird st_mtime durch das Anlegen oder Löschen von Dateien in diesem Verzeichnis geändert. Das Feld st_mtime wird nicht durch Ändern von Besitzer, Gruppe, Hardlink-Zähler oder Modus verändert.

Das Feld st_ctime wird durch Beschreiben oder Setzen der Inode-Informationen geändert (d.h. Besitzer, Gruppe, Link-Zähler, Modus etc.).

POSIX refers to the st_mode bits corresponding to the mask S_IFMT (see below) as the file type, the 12 bits corresponding to the mask 07777 as the file mode bits and the least significant 9 bits (0777) as the file permission bits.

Die folgende Maskenwerte sind für den Dateityp des Feldes st_mode definiert:

Um beispielsweise eine reguläre Datei zu testen, könnten Sie Folgendes verwenden:

stat(pathname, &sb);
if ((sb.st_mode & S_IFMT) == S_IFREG) {
    /* reguläre Datei verarbeiten */
}

Da Tests der obigen Form häufig sind, definiert POSIX zusätzliche Makros, um präzisere Tests des Dateityps in st_mode zu ermöglichen:

Der obige Code-Schnipsel sollte daher folgendermaßen geändert werden:

stat(pathname, &sb);
if (S_ISREG(sb.st_mode)) {
    /* reguläre Datei verarbeiten */
}

Die Definitionen der meisten der oben genannten Testmakros für Dateitypen werden bereitgestellt, sofern irgendeines der folgenden Feature-Test-Makros definiert ist: _BSD_SOURCE (in Glibc 2.19 und früher), _SVID_SOURCE (in Glibc 2.19 und früher) oder _DEFAULT_SOURCE (in Glibc 2.20 und neuer). Zusätzlich werden Definitionen aller oben genannten Makros außer S_IFSOCK und S_ISSOCK() bereitgestellt, wenn _XOPEN_SOURCE definiert ist. Die Definition von S_IFSOCK kann auch durch Setzen von _XOPEN_SOURCE auf einen Wert von 500 oder größer erreicht werden.

Die Definition von S_ISSOCK() ist verfügbar, wenn eines der folgenden Feature-Test-Makros definiert ist: _BSD_SOURCE (in Glibc 2.19 und früher), _DEFAULT_SOURCE (in Glibc 2.20 und früher), _XOPEN_SOURCE mit einem Wert von 500 oder größer oder _POSIX_C_SOURCE mit einem Wert von 200112L oder größer.

Die folgende Maskenwerte sind für die Dateimodus-Komponente des Felds st_mode definiert:

Das SGID-Bit (S_ISGID) hat verschiedene besondere Nutzungsmöglichkeiten: Für ein Verzeichnis bedeutet es, das die BSD-Semantik Anwendung findet: Dateien, die in ihm erzeugt werden, erben die Gruppen-ID des Verzeichnisses und nicht die effektive Gruppen-ID des erzeugenden Prozesses, und dort erzeugte Verzeichnisse haben das SGID-Bit ebenfalls gesetzt. Für eine Datei, bei der das Bit für Gruppenausführungsrechte (S_IXGRP) nicht gesetzt ist, bedeutet es erzwungenes Sperren von Datei/Datensatz.

Das »Sticky«-Bit (S_ISVTX) an einem Verzeichnis bedeutet, dass eine Datei in diesem Verzeichnis nur vom Besitzer der Datei, dem Besitzer des Verzeichnisses, und von einem privilegierten Prozess umbenannt und gelöscht werden darf.

Bei Erfolg wird Null zurückgegeben. Bei einem Fehler wird -1 zurückgegeben und errno entsprechend gesetzt.

EACCES

Der Suchzugriff auf eines der Verzeichnisse im Pfadpräfix von Pfadname wurde verweigert (siehe auch path_resolution(7)).

EBADF

fd ist falsch.

EFAULT

Ungültige Adresse

ELOOP

Beim Pfaddurchlauf wurden zu viele symbolische Links gefunden.

ENAMETOOLONG

Pfadname ist zu lang.

ENOENT

Eine Komponente von Pfadname existiert nicht oder Pfadname ist die leere Zeichenkette.

ENOMEM

Kein Speicher mehr (das bedeutet Speicher im Kernel).

ENOTDIR

Eine Komponente des Pfadpräfixes von Pfadname ist kein Verzeichnis.

EOVERFLOW

Pfadname oder fd bezieht sich auf eine Datei, deren Name, Inode-Anzahl oder Anzahl der Blöcke nicht durch die Typen off_t, ino_t oder blkcnt_t repräsentiert werden kann. Dieser Fehler kann beispielsweise auftreten, wenn eine auf einer 32-bit-Plattform kompilierte Anwendung ohne -D_FILE_OFFSET_BITS=64 stat() für eine Datei aufruft, deren Größe (1<<31)-1 Byte übersteigt.

Die folgenden Fehler können zusätzlichen bei fstatat() auftreten:

EBADF

dirfd ist kein zulässiger Dateideskriptor.

EINVAL

Unzulässiger Schalter in Schalter angegeben.

ENOTDIR

Pfadname ist relativ und dirfd ist ein Dateideskriptor, der sich auf eine Datei statt auf ein Verzeichnis bezieht.

fstatat() wurde zu Linux in Kernel 2.6.16 hinzugefügt; Bibliotheksunterstützung wurde zu Glibc in Version 2.4 hinzugefügt.

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

fstatat(): POSIX.1-2008.

Entsprechend POSIX.1-2001 benötigt lstat() bei Anwendung auf einen symbolischen Link lediglich im Feld st_size und im Dateityp des st_mode-Feldes der stat-Struktur gültige Rückgabeinformationen. POSIX.1-2008 engt diese Spezifikation ein, indem lstat() in allen Feldern außer den Modus-Bits in st_mode gültige Informationen zurückgeben muss.

Die Verwendung der Felder st_blocks und st_blksize kann die Portabilität einschränken. Diese wurden in BSD eingeführt. Die Interpretation unterscheidet sich auf verschiedenen Systemen, und möglicherweise auf einem einzelnen System, wenn NFS-Einhängungen bestehen. Falls Sie die Definition der Typen blkcnt_t oder blksize_t von <sys/stat.h> ermitteln wollen, dann definieren Sie _XOPEN_SOURCE mit einem Wert von 500 oder größer (bevor Sie irgendeine Header-Datei einbeziehen).

POSIX beschreibt die Konstanten S_IFMT, S_IFSOCK, S_IFLNK, S_IFREG, S_IFBLK, S_IFDIR, S_IFCHR, S_IFIFO, S_ISVTX nicht, sondern verlangt stattdessen die Benutzung der Makros S_ISDIR() etc. Die S_IF*-Konstanten sind in POSIX.1-2001 und neuer vorhanden.

Die Makros S_ISLNK() und S_ISSOCK() finden sich nicht in POSIX.1-1996, sind aber beide in POSIX.1-2001 vorhanden; ersteres ist aus SVID 4v2, letzteres aus SUSv2.

UNIX V7 (und später) hat S_IREAD, S_IWRITE, S_IEXEC, wobei POSIX die Synonyme S_IRUSR, S_IWUSR, S_IXUSR vorschreibt.

Unter Linux löst lstat() generell keine Automounter-Aktion aus, während stat() dies tut (aber siehe fstatat(2)).

Für die meisten Dateien unterhalb des Verzeichnisses /proc liefert stat() nicht die Dateigröße im Feld st_size zurück, stattdessen wird das Feld mit dem Wert 0 zurückgeliefert.

Das folgende Programm ruft stat() auf zeigt ausgewählte Felder der zurückgelieferten Struktur stat an.

#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, "Aufruf: %s <Pfadname>\n", argv[0]);
        exit(EXIT_FAILURE);
    }
    if (stat(argv[1], &sb) == -1) {
        perror("stat");
        exit(EXIT_FAILURE);
    }
    printf("Dateityp:                 ");
    switch (sb.st_mode & S_IFMT) {
    case S_IFBLK:  printf("blockorientiertes Gerät\n");   break;
    case S_IFCHR:  printf("zeichenorientiertes Gerät\n"); break;
    case S_IFDIR:  printf("Verzeichnis\n");               break;
    case S_IFIFO:  printf("FIFO/Pipe\n");                 break;
    case S_IFLNK:  printf("symbolischer Link\n");         break;
    case S_IFREG:  printf("reguläre Datei\n");            break;
    case S_IFSOCK: printf("Socket\n");                    break;
    default:       printf("unbekannt?\n");                break;
    }
    printf("I-node number:            %ld\n", (long) sb.st_ino);
    printf("Modus:                    %lo (oktal)\n",
            (unsigned long) sb.st_mode);
    printf("Link count:               %ld\n", (long) sb.st_nlink);
    printf("Ownership:                UID=%ld   GID=%ld\n",
            (long) sb.st_uid, (long) sb.st_gid);
    printf("Preferred I/O block size: %ld bytes\n",
            (long) sb.st_blksize);
    printf("File size:                %lld bytes\n",
            (long long) sb.st_size);
    printf("Blocks allocated:         %lld\n",
            (long long) sb.st_blocks);
    printf("Letzte Statusänderung:    %s", ctime(&sb.st_ctime));
    printf("Letzter Dateizugriff:     %s", ctime(&sb.st_atime));
    printf("Letzte Dateiänderung:     %s", ctime(&sb.st_mtime));
    exit(EXIT_SUCCESS);
}

ls(1), stat(1), access(2), chmod(2), chown(2), readlink(2), utime(2), capabilities(7), symlink(7)

Diese Seite ist Teil der Veröffentlichung 4.04 des Projekts Linux-man-pages. Eine Beschreibung des Projekts, Informationen, wie Fehler gemeldet werden können sowie die aktuelle Version dieser Seite finden sich unter http://www.kernel.org/doc/man-pages/.

Die deutsche Übersetzung dieser Handbuchseite wurde von Jonas Rovan <jonas@blitz.de>, Martin Schulze <joey@infodrom.org>, Michael Piefel <piefel@debian.org>, Helge Kreutzmann <debian@helgefjell.de> und Mario Blättermann <mario.blaettermann@gmail.com> erstellt.

Diese Übersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 oder neuer bezüglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG übernommen.

Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an <debian-l10n-german@lists.debian.org>.