NAZWA¶

stat, fstat, lstat - pobieranie stanu pliku

SKŁADNIA¶

#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);
Wymagane ustawienia makr biblioteki glibc (patrz feature_test_macros(7)):
lstat():

OPIS¶

Funkcje te zwracają informacje o podanym pliku. Do uzyskania tej informacji nie są wymagane prawa dostępu do samego pliku, lecz — w przypadku stat() i lstat() — konieczne są prawa wykonywania (przeszukiwania) do wszystkich katalogów na prowadzącej do pliku ścieżce path. stat() zwraca status pliku wskazywanego przez path, ładując go do argumentu buf. lstat() jest identyczny z stat(), lecz w przypadku gdy path jest dowiązaniem symbolicznym, to zwraca status tego dowiązania, a nie pliku, do którego się to dowiązanie odwołuje. fstat() jest identyczny z stat(), z tym wyjątkiem, że plik, którego status ma zwrócić, jest określony przez deskryptor pliku fd. Wszystkie te funkcje zwracają strukturę stat, zawierającą następujące pola:

struct stat {
    dev_t     st_dev;      /* ID urządzenia zawierającego plik */
    ino_t     st_ino;      /* numer i-węzła (inode) */
    umode_t   st_mode;     /* ochrona */
    nlink_t   st_nlink;    /* liczba dowiązań stałych (hardlinks) */
    uid_t     st_uid;      /* ID użytkownika właściciela */
    gid_t     st_gid;      /* ID grupy właściciela */
    dev_t     st_rdev;     /* ID urządzenia (jeśli plik specjalny) */
    off_t     st_size;     /* całkowity rozmiar w bajtach */
    blksize_t st_blksize;  /* wielkość bloku dla I/O systemu plików */
    blkcnt_t  st_blocks;   /* liczba zaalokowanych bloków 512-bajtowych */
    time_t    st_atime;    /* czas ostatniego dostępu */
    time_t    st_mtime;    /* czas ostatniej modyfikacji */
    time_t    st_ctime;    /* czas ostatniej zmiany */
};

Pole st_dev opisuje urządzenie, w którym plik się znajduje. (Makra major(3) i minor(3) mogą się przydać przy dekodowaniu identyfikatora urządzenia znajdującego się w tym polu). Pole st_rdev opisuje urządzenie reprezentowane przez ten plik (i-węzeł). Pole st_size podaje rozmiar pliku w bajtach (jeżeli plik jest plikiem regularnym lub dowiązaniem symbolicznym). Rozmiarem dowiązania symbolicznego jest długość ścieżki, na którą wskazuje, z wyłączeniem końcowego bajtu NULL. Pole st_sblocks określa liczbę bloków zajmowanych przez plik w jednostkach 512-bajtowych. (Liczba ta może być mniejsza niż st_size/512, na przykład wtedy, gdy plik ma dziury). Pole st_blksize zawiera "preferowany" rozmiar bloku dla efektywnych operacji wejścia/wyjścia dla pliku. (Zapis do pliku mniejszych kawałków może spowodować nieefektywne operacje odczyt-modyfikacja-powtórny zapis). Nie wszystkie systemy plików pod Linuksem obsługują wszystkie pola czasu. Niektóre systemy plików można zamontować w ten sposób, że dostęp do pliku lub katalogu nie powoduje uaktualnienia pola st_atime. (Patrz noatime, nodiratime i relatime w mount(8) oraz powiązane informacje w mount(2)). Dodatkowo st_atime nie jest aktualizowane, jeśli plik jest otwierany z flagą O_NOATIME, patrz open(2). Pole st_atime jest zmieniane przez każdy dostęp do pliku, np. przez execve(2), mknod(2), pipe(2), utime(2) i read(2) (w razie odczytania więcej niż zera bajtów). Inne procedury, jak mmap(2) mogą, ale nie muszą, zaktualizować st_atime. Zazwyczaj pole st_mtime jest zmieniane przez modyfikowanie pliku, np. przez mknod(2), truncate(2), utime(2) i write(2) (więcej niż zera bajtów). Co więcej st_mtime katalogu jest zmieniane przy tworzeniu plików w tym katalogu lub ich usuwaniu. Pole st_mtime nie jest zmieniane po zmianach właściciela, grupy, liczby dowiązań (hard links) czy uprawnień. Pole st_ctime jest zmieniane przy zapisywaniu lub ustawianiu informacji i-węzła (np. właściciela, grupy, liczby dowiązań, praw itp.). Zdefiniowane są następujące makra POSIX sprawdzające typ pliku przy użyciu pola st_mode: Dla pola st_mode zdefiniowano następujące flagi:

S_IFMT	0170000	maska bitowa dla pól bitowych typu pliku
S_IFSOCK	0140000	gniazdo
S_IFLNK	0120000	dowiązanie symboliczne (symbolic link)
S_IFREG	0100000	plik regularny
S_IFBLK	0060000	urządzenie blokowe
S_IFDIR	0040000	katalog
S_IFCHR	0020000	urządzenie znakowe
S_IFIFO	0010000	kolejka FIFO
S_ISUID	0004000	bit "set UID"
S_ISGID	0002000	bit "set-group-ID" (patrz niżej)
S_ISVTX	0001000	bit "sticky" (patrz niżej)
S_IRWXU	00700	maska praw dostępu właściciela pliku
S_IRUSR	00400	właściciel ma prawa odczytu
S_IWUSR	00200	właściciel ma prawa zapisu
S_IXUSR	00100	właściciel ma prawa wykonania
S_IRWXG	00070	maska praw dostępu dla grupy
S_IRGRP	00040	grupa ma prawa odczytu
S_IWGRP	00020	grupa ma prawa zapisu
S_IXGRP	00010	grupa ma prawa wykonania
S_IRWXO	00007	maska uprawnień dla innych (poza grupą)
S_IROTH	00004	inni mają prawa odczytu
S_IWOTH	00002	inni mają prawa zapisu
S_IXOTH	00001	inni mają prawa wykonania

Bit "set-group-ID" ( S_ISGID) ma kilka specjalnych znaczeń. Ustawiony na katalogu oznacza, że dla tego katalogu powinna być używana semantyka BSD: pliki w nim utworzone dziedziczą identyfikator grupy z katalogu, a nie z efektywnego identyfikatora grupy procesu tworzącego plik, ponadto tworzone katalogi będą miały także ustawiony bit S_ISGID. Dla pliku, który nie ma ustawionego bitu wykonywania dla grupy ( S_IXGRP), bit "set-group-ID" oznacza obowiązkowe blokowanie pliku/rekordu. Bit "sticky" ( S_ISVTX) ustawiony na katalogu oznacza, że tylko właściciel pliku lub właściciel katalogu albo proces uprzywilejowany może usunąć plik w tym katalogu lub zmienić nazwę tego pliku.

WARTOŚĆ ZWRACANA¶

W przypadku powodzenia zwracane jest zero. W razie wystąpienia błędu zwracane jest -1 i ustawiana jest odpowiednia wartość zmiennej errno.

BŁĘDY¶

EACCES

Brak uprawnień do przeszukiwania jednego z katalogów w ścieżce zaczynającej path. (Patrz także path_resolution(7)).

EBADF

fd jest nieprawidłowy.

EFAULT

Niepoprawny adres.

ELOOP

Podczas rozwiązywania ścieżki napotkano zbyt wiele dowiązań symbolicznych.

ENAMETOOLONG

Ścieżka path jest zbyt długa.

ENOENT

Składnik ścieżki path nie istnieje lub path jest pustym łańcuchem znaków.

ENOMEM

Brak pamięci (tj. pamięci jądra).

ENOTDIR

Składnik ścieżki path nie jest katalogiem.

EOVERFLOW

(stat()) path odnosi się do pliku, którego rozmiar nie jest reprezentowalny w typie off_t. Może się to zdarzyć, jeśli aplikacja skompilowana na platformie 32-bitowej bez -D_FILE_OFFSET_BITS=64 wywoła stat() na pliku, którego rozmiar jest większy niż (1<<31)-1 bitów.

ZGODNE Z¶

Opisywane wywołanie systemowe są zgodne z SVr4, BSD 4.3, POSIX.1-2001. Według POSIX.1-2001 lstat() na dowiązaniu symbolicznym powinien zwrócić poprawne wartości tylko w polu st_size i w części pola st_mode związanej z typem pliku struktury stat. POSIX.1-2008 zaostrza tę specyfikację, wymagając od lstat() zwracania poprawnych informacji we wszystkich polach z wyjątkiem bitów uprawnień w st_mode. Używanie pól st_blocks i st_blksize może być nieprzenośne. (Były wprowadzone w BSD. Interpretacje różnią się zarówno między systemami, jak i na jednym systemie, jeśli użyty jest zdalny system plików montowany po NFS-ie). Aby uzyskać definicje typów blkcnt_t i blksize_t z <sys/stat.h> należy zdefiniować _XOPEN_SOURCE na wartość 500 lub wyższą (przed dołączeniem jakiegokolwiek innego pliku nagłówkowego). POSIX.1-1990 nie opisywał stałych S_IFMT, S_IFSOCK, S_IFLNK, S_IFREG, S_IFBLK, S_IFDIR, S_IFCHR, S_IFIFO, S_ISVTX , ale zamiast tego wymagał używania makr S_ISDIR() itp. Stałe S_IF* są obecne w POSIX.1-2011 i późniejszych. Makra S_ISLNK() i S_ISSOCK() nie są wymienione w POSIX.1-1996, ale są obecne w POSIX.1-2001; pierwsze z nich pochodzi z SVID 4, a drugie z SUSv2. Unix V7 (i kolejne systemy) miał S_IREAD, S_IWRITE, S_IEXEC, podczas gdy POSIX nakazuje używanie synonimów S_IRUSR, S_IWUSR, S_IXUSR.

Inne systemy¶

Wartości, które były (lub nadal są) w użyciu w różnych systemach:

szesn.	nazwa	ls	ósemk.	opis
f000	S_IFMT		170000	maska bitowa dla pól bitowych typu pliku
0000			000000	niedziałający i-węzeł w SCO, nieznany typ
				w BSD; SVID-v2 i XPG2 mają zarówno
				0, jak i 0100000 dla zwykłego pliku
1000	S_IFIFO	p|	010000	kolejka FIFO (potok nazwany)
2000	S_IFCHR	c	020000	specjalny znakowy (V7)
3000	S_IFMPC		030000	specjalny znakowy zwielokrotniony (V7)
4000	S_IFDIR	d/	040000	katalog (V7)
5000	S_IFNAM		050000	nazwany plik specjalny XENIXa
				z dwoma podtypami, rozróżnianymi przez
				wartości 1, 2 w st_rdev
0001	S_INSEM	s	000001	podtyp IFNAM semafora XENIX
0002	S_INSHD	m	000002	podtyp IFNAM dzielonych danych XENIX
6000	S_IFBLK	b	060000	specjalny blokowy (V7)
7000	S_IFMPB		070000	specjalny blokowy zwielokrotniony (V7)
8000	S_IFREG	-	100000	regularny (V7)
9000	S_IFCMP		110000	skompresowany VxFS
9000	S_IFNWK	n	110000	sieciowy specjalny (HP-UX)
a000	S_IFLNK	l@	120000	dowiązanie symboliczne (BSD)
b000	S_IFSHAD		130000	shadow i-węzeł ACL w Solarisie
				(niedostępny w przestrzeni użytkownika)
c000	S_IFSOCK	s=	140000	gniazdo (BSD; także "S_IFSOC" na VxFS)
d000	S_IFDOOR	D>	150000	drzwi Solarisa
e000	S_IFWHT	w%	160000	BSD whiteout (nieużywane dla i-węzła)
0200	S_ISVTX		001000	"bit sticky": zachowuje wyswappowany tekst
				nawet po użyciu (V7)
				zarezerwowane (SVID-v2)
				Dla niekatalogów: nie buforuj tego
				pliku (SunOS)
				Dla katalogów: flaga ograniczonego
				usuwania (SVID-v4.2)
0400	S_ISGID		002000	set-group-ID podczas wykonywania (V7)
				dla katalogów: używa semantyki BSD do
				propagowania ID grupy
0400	S_ENFMT		002000	egzekwowanie blokowania plików SysV
				(dzielone z S_ISGID)
0800	S_ISUID		004000	set-user-ID podczas wykonywania (V7)
0800	S_CDF		004000	katalog jest plikiem zależnym od kontekstu
				(HP-UX)

Polecenie "sticky" pojawiło się w wersji 32V systemu AT&T UNIX.

UWAGI¶

Od wersji jądra 2.5.48 struktura stat obsługuje nanosekundową dokładność wszystkich trzech pól czasowych. Glibc podaje nanosekundową część każdego z tych pól, używając albo st_atim.tv_nsec, jeżeli zdefiniowano makro _BSD_SOURCE lub _SVID_SOURCE. Pola te są podane w POSIX.1-2008 i w związku z tym, począwszy od wersji 2.12 biblioteka glibc udostępnia nazwy tych pól, jeśli _POSIX_C_SOURCE jest zdefiniowane na wartość 200809L lub większą, albo _XOPEN_SOURCE jest zdefiniowane na wartość 700 lub większą. Jeśli nie zdefiniowano żadnego z powyższych makr, to nanosekundowe wartości są dostępne w polu st_atimensec. W systemach plików, które nie obsługują takiej dokładności czasowej, wartości nanosekund w tych polach wynoszą 0. Pod Linuksem, lstat() nie spowoduje uruchomienia akcji automontera, natomiast stat() - spowoduje (patrz jednakże fstatat(2)). Dla większości plików w katalogu /proc, stat() w polu st_size zwraca 0, a nie rzeczywisty rozmiar pliku.

Interfejs jądra¶

Z upływem czasu, zwiększanie rozmiarów struktury stat doprowadziło do powstania trzech kolejnych wersji funkcji stat(): sys_stat() (slot __NR_oldstat), sys_newstat() (slot __NR_stat) i sys_stat64() (nowe w jądrze 2.4; slot __NR_stat64). Funkcja opakowująca stat() biblioteki glibc ukrywa te szczegóły przed aplikacjami, wywołując najnowszą wersję wywołania systemowego dostarczanego przez jądro i przepakowując zwracaną informację, jeśli jest to wymagane przez starsze aplikacje. Podobne uwagi odnoszą się do fstat() i lstat().

PRZYKŁAD¶

Poniższy program wywołuje stat() i wypisuje wybrane pola zwrócone w strukturze stat:

#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, "Użycie: %s <ścieżka>\n", argv[0]);
        exit(EXIT_FAILURE);
    }

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

    printf("Typ pliku:                 ");

    switch (sb.st_mode & S_IFMT) {
    case S_IFBLK:  printf("urządzenie blokowe\n");      break;
    case S_IFCHR:  printf("urządzenie znakowe\n");      break;
    case S_IFDIR:  printf("katalog\n");                 break;
    case S_IFIFO:  printf("FIFO/pipe\n");               break;
    case S_IFLNK:  printf("dowiązanie symboliczne\n");  break;
    case S_IFREG:  printf("zwykły plik\n");             break;
    case S_IFSOCK: printf("gniazdo\n");                 break;
    default:       printf("typ nieznany\n");            break;
    }

    printf("numer I-węzła:            %ld\n", (long) sb.st_ino);

    printf("Tryb:                     %lo (octal)\n",
            (unsigned long) sb.st_mode);

    printf("Liczba dowiązań:           %ld\n", (long) sb.st_nlink);
    printf("Właściciel:                UID=%ld   GID=%ld\n",
            (long) sb.st_uid, (long) sb.st_gid);

    printf("Preferowany rozmiar bloku I/O: %ld bajtów\n",
            (long) sb.st_blksize);
    printf("Rozmiar bloku:                 %lld bajtów\n",
            (long long) sb.st_size);
    printf("Liczba zaalokowanych bloków:   %lld\n",
            (long long) sb.st_blocks);

    printf("Ostatnia zmiana stanu:    %s", ctime(&sb.st_ctime));
    printf("Ostatni dostęp do pliku:  %s", ctime(&sb.st_atime));
    printf("Ostatnia zmiana pliku:    %s", ctime(&sb.st_mtime));

    exit(EXIT_SUCCESS);
}

ZOBACZ TAKŻE¶

access(2), chmod(2), chown(2), fstatat(2), readlink(2), utime(2), capabilities(7), symlink(7)

O STRONIE¶

Angielska wersja tej strony pochodzi z wydania 3.40 projektu Linux man-pages. Opis projektu oraz informacje dotyczące zgłaszania błędów można znaleźć pod adresem http://www.kernel.org/doc/man-pages/.

TŁUMACZENIE¶

Autorami polskiego tłumaczenia niniejszej strony podręcznika man są: Przemek Borys (PTM) <pborys@dione.ids.pl> i Robert Luberda <robert@debian.org>. Polskie tłumaczenie jest częścią projektu manpages-pl; uwagi, pomoc, zgłaszanie błędów na stronie http://sourceforge.net/projects/manpages-pl/. Jest zgodne z wersją 3.40 oryginału.