Ubuntu Manpage: stat, fstat, lstat, fstatat

bezeichnung
übersicht
beschreibung
rückgabewert
fehler
versionen
konform zu
anmerkungen
beispiel
siehe auch
kolophon
übersetzung

BEZEICHNUNG

       stat, fstat, lstat, fstatat - Dateistatus ermitteln

ÜBERSICHT

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

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

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

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

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

       lstat():
           /* Glibc 2.19 und älter */ _BSD_SOURCE
               || /* Seit Glibc 2.20 */ _DEFAULT_SOURCE
               || _XOPEN_SOURCE >= 500
               || /* Seit Glibc 2.10: */ _POSIX_C_SOURCE >= 200112L

       fstatat():
           Seit Glibc 2.10:
               _POSIX_C_SOURCE >= 200809L
           Vor Glibc 2.10:
               _ATFILE_SOURCE

BESCHREIBUNG

Diese Funktionen geben Informationen über eine Datei im Puffer zurück, auf den statbuf 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.

Die Struktur stat
Alle diese Systemaufrufe geben eine Struktur 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; /* Dateityp und -modus */
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.

Hinweis: Zur Leistungsverbesserung und aus Einfachheitsgründen können verschiedene Felder in der Struktur
stat Zustandsinformationen von verschiedenen Zeitpunkten während der Ausführung des Systemaufrufs
enthalten. Wird beispielsweise st_mode oder st_uid von einem anderen Prozess während der Ausführung des
Systemaufrufs durch Aufruf von chmod(2) oder chown(2) geändert, dann könnte stat() den alten st_mode
zusammen mit dem neuen st_uid oder den alten st_uid zusammen mit dem neuen st_mode zurückliefern.

Die Bedeutung der Felder in stat im Einzelnen:

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

st_ino Dieses Feld enthält die Inode-Nummer der Datei.

st_mode
Dieses Feld enthält den Dateityp und -modus. Siehe inode(7) für weitere Informationen.

st_nlink
Dieses Feld enthält die Anzahl der harten Links auf die Datei.

st_uid Dieses Feld enthält die Benutzerkennung des Feldeigentümers.

st_gid Dieses Feld enthält die Kennung des Gruppeneigentümers der Datei.

st_rdev
Dieses Feld beschreibt das Gerät, das diese Datei (Inode) repräsentiert.

st_size
Dieses Feld 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.

st_blksize
Dieses Feld liefert die »bevorzugte« Blockgröße für effiziente Dateisystem-E/A.

st_blocks
Dieses Feld 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.

st_atime
Dies ist der Zeitstempel des letzten Dateizugriffs.

st_mtime
Dies ist der Zeitstempel der letzten Dateiveränderung.

st_ctime
Dies ist der Zeitstempel der letzten Dateistatusveränderung.

Für weitere Informationen zu den obigen Feldern siehe inode(7).

fstatat()
Der Systemaufruf fstatat() ist eine allgemeinere Schnittstelle zum Zugriff auf Dateiinformationen, die
immer noch das gleiche Verhalten wie einer aus stat(), lstat() und fstat() bereitstellen kann.

Falls der in Pfadname übergebene Pfadname relativ ist, wird er als relativ zu dem im Dateideskriptor
dirfd referenzierten Verzeichnis interpretiert (statt relativ zum aktuellen Arbeitsverzeichnis des
aufrufenden Prozesses, wie es bei stat() und lstat() für einen relativen Pfadnamen erfolgt).

Falls Pfadname relativ ist und dirfd den besonderen Wert AT_FDCWD annimmt, wird Pfadname als relativ zum
aktuellen Arbeitsverzeichnis des aufrufenden Prozesses interpretiert (wie stat() und lstat()).

Falls Pfadname absolut ist wird dirfd ignoriert.

Schalter kann entweder 0 sein oder durch bitweises ODER eines oder mehrere der folgenden Schalter gesetzt
haben:

AT_EMPTY_PATH (seit Linux 2.6.39)
Falls Pfadname eine leere Zeichenkette ist, wird mit der Datei gearbeitet, auf die dirfd verweist
(dies kann mit dem O_PATH-Schalter von open(2) ermittelt werden). In diesem Fall kann sich dirfd
auf jeden Dateityp beziehen, nicht nur einem Verzeichnis und das Verhalten von fstatat() ist
ähnlich zu dem von fstat(). Falls dirfd AT_FDCWD ist, erfolgt der Aufruf im aktuellen
Arbeitsverzeichnis. Dieser Schalter ist Linux-spezifisch; definieren Sie _GNU_SOURCE, um dessen
Definition zu ermitteln.

AT_NO_AUTOMOUNT (seit Linux 2.6.38)
Die Terminal-»basename«-Komponente von Pfadname wird nicht automatisch eingehängt, wenn es ein
Verzeichnis ist, das selbst ein Selbsteinhängepunkt ist. Dies ermöglicht dem Aufrufenden,
Informationen zu einem Auto-Einhängepunkt zu sammeln, anstatt zu dem Ort, der eingehängt werden
würde. Seit Linux 4.14 realisiert dies keinen nicht existierenden Namen in einem
bei-Bedarf-Verzeichnis, sie für indirekte Zuordnungen von Selbsteinhängeprogrammen verwandt
werden. Dieser Schalter kann in Werkzeugen verwendet werden, die Verzeichnisse einlesen, um
automatische Masseneinhängungen eines Verzeichnisses zu verhindern, welches Auto-Einhängepunkte
enthält. Der Schalter AT_NO_AUTOMOUNT ist unwirksam, wenn der Einhängepunkt bereits eingehängt
wurde. Dieser Schalter ist Linux-spezifisch; definieren Sie _GNU_SOURCE, um dessen Definition zu
ermitteln. Sowohl stat() und lstat() handeln, als ob AT_NO_AUTOMOUNT gesetzt worden wäre.

AT_SYMLINK_NOFOLLOW
Falls Pfadname ein symbolischer Link ist, wird er nicht dereferenziert: Stattdessen werden
Informationen zum Link selbst zurückgegeben, wie lstat(). In der Voreinstellung dereferenziert
fstatat() symbolische Links, wie auch stat().

Lesen Sie openat(2) für eine Beschreibung der Notwendigkeit von fstatat().

RÜCKGABEWERT

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

FEHLER

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

EBADF fd ist kein zulässiger offener Dateideskriptor.

EFAULT Ungültige Adresse.

ELOOP Beim Pfaddurchlauf wurden zu viele symbolische Links gefunden.

ENAMETOOLONG
pathname ist zu lang.

ENOENT Eine Komponente von pathname existiert nicht oder ist ein toter symbolischer Link.

ENOENT Pfadname ist die leere Zeichenkette und AT_EMPTY_PATH wurde in Schalter nicht festgelegt.

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 flags angegeben.

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

VERSIONEN

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

KONFORM ZU

       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.

ANMERKUNGEN

Zeitstempelfelder
Ältere Kernel und ältere Standards unterstützen keine Zeitstempel-Felder für Nanosekunden. Stattdessen
gab es die drei Zeitstempel-Felder – st_atime, st_mtime und st_ctime –, angegeben als time_t, die
Zeitstempel mit Sekundengenauigkeit ergaben.

Seit Kernel 2.5.48 unterstützt die stat-Struktur die Nanosekunden-Auflösung für die drei
Zeitstempel-Felder. Die Nanosekunden-Komponenten jedes Zeitstempels sind durch Namen der Form
st_atim.tv_nsec verfügbar, falls geeignete Feature-Test-Makros definiert sind. Nanosekunden-Zeitstempel
wurden in POSIX.1-2008 standardisiert und seit Glibc-Version 2.12 legt Glibc die
Nanosekundenkomponentennamen offen, falls _POSIX_C_SOURCE mit einem Wert von 200809L oder größer oder
_XOPEN_SOURCE mit einem Wert von 700 oder größer definiert ist. Bis einschließlich Glibc 2.19 sind die
Definitionen der Nanosekundenkomponenten auch definiert, falls _BSD_SOURCE oder _SVID_SOURCE definiert
sind. Falls keines der erwähnten Makros definiert ist, dann werden die Nanosekunden-Werte mit Namen der
Form st_atimensec angezeigt.

Unterschiede C-Bibliothek/Kernel
Mit der Zeit führte der Größenzuwachs der stat-Struktur auf 32-Bit-Plattformen wie i386 zu drei
Folgeversionen von stat(): sys_stat() (slot __NR_oldstat), sys_newstat() (slot __NR_stat) und
sys_stat64() (slot __NR_stat64). Die ersten zwei Versionen waren bereits in Linux 1.0. (allerdings mit
anderen Namen) verfügbar; die letzte wurde in Linux 2.4 hinzugefügt. Ähnliches gilt für fstat() und
lstat().

Die Kernel-interne Version der Struktur stat handhabte drei verschieden Versionen, und zwar:

__old_kernel_stat
Die ursprüngliche Struktur, mit eher engen Felder und keiner Auffüllung.

stat Größeres Feld st_ino mit ergänzter Auffüllung an verschiedenen Teilen der Struktur, um zukünftige
Erweiterungen zu erlauben.

stat64 Noch größeres Feld st_ino, größere Felder st_uid und st_gid, um der Linux-2.4-Erweiterung der UIDs
und GIDs auf 32 bit Platz zu schaffen, und verschiedene andere vergrößerte Felder und weitere
Auffüllungen in der Struktur. (Verschiedene Auffüllbytes wurden schließlich in Linux 2.6 mit dem
Aufkommen von 32-bit-Gerätekennungen und Nanosekundenkomponenten der Zeitstempelfelder benutzt.)

Die Wrapperfunktion der Glibc stat() versteckt diese Details vor Anwendungen. Sie ruft die neuste Version
des vom Kernel bereitgestellten Systemaufrufs auf und packt die zurückgelieferten Informationen neu,
falls dies für alte Programme benötigt wird.

Auf modernen 64-Bit-Systemen ist das Leben einfacher: Es gibt einen einzigen Systemaufruf stat() und der
Kernel arbeitet mit einer Struktur stat, die Felder einer ausreichenden Größe enthält.

Der der Glibc-Wrapper-Funktion fstatat() zugrunde liegende Systemaufruf ist tatsächlich fstatat64() oder
auf einigen Architekturen newfstatat().

BEISPIEL

       Das folgende Programm ruft lstat() 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>
       #include <sys/sysmacros.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 (lstat(argv[1], &sb) == -1) {
               perror("lstat");
               exit(EXIT_FAILURE);
           }

           printf("Kennung des enthaltenen Gerätes:  [%lx,%lx]\n",
                (long) major(sb.st_dev), (long) minor(sb.st_dev));

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

SIEHE AUCH

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

KOLOPHON

       Diese  Seite  ist  Teil  der  Veröffentlichung  5.03  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 https://www.kernel.org/doc/man-pages/.

ÜBERSETZUNG

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