stat(2) System Calls Manual stat(2) NAZWA stat, fstat, lstat, fstatat - pobiera stan pliku BIBLIOTEKA Standardowa biblioteka C (libc, -lc) SKLADNIA #include 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 /* Definicja stalych AT_* */ #include int fstatat(int dirfd, const char *restrict path, struct stat *restrict statbuf, int flags); Wymagane ustawienia makr biblioteki glibc (patrz feature_test_macros(7)): lstat(): /* Od glibc 2.20 */ _DEFAULT_SOURCE || _XOPEN_SOURCE >= 500 || /* Od glibc 2.10: */ _POSIX_C_SOURCE >= 200112L || /* glibc 2.19 i wczesniejsze */ _BSD_SOURCE fstatat(): Od glibc 2.10: _POSIX_C_SOURCE >= 200809L Przed glibc 2.10: _ATFILE_SOURCE OPIS Funkcje te zwracaja informacje o podanym pliku w buforze wskazanym przez statbuf. Do uzyskania tej informacji nie sa wymagane prawa dostepu do samego pliku, lecz -- w przypadku stat, fstatat() i lstat() -- konieczne sa prawa wykonywania (przeszukiwania) do wszystkich katalogow na prowadzacej do pliku sciezce path. stat() i fstatat() pobieraja informacje o pliku wskazanym przez path; cechy wyrozniajace fstatat() opisano ponizej. lstat() jest identyczny z stat(), lecz w przypadku gdy path jest dowiazaniem symbolicznym, to zwraca informacje o samym dowiazaniu, a nie pliku, do ktorego sie to dowiazanie odwoluje. fstat() jest identyczny z stat(), z tym wyjatkiem, ze plik o ktorym maja byc pobrane informacje, jest okreslony przez deskryptor pliku fd. Struktura stat Wszystkie te funkcje zwracaja strukture stat (zob. stat(3type)). Uwaga: Dla zachowania wydajnosci i prostoty, rozne pola w strukturze stat moga zawierac stany z roznych momentow wykonywania wywolania systemowego. Przykladowo, jesli st_mode lub st_uid zostanie zmieniony przez inny proces za pomoca wywolania chmod(2) lub chown(2), stat() moze zwrocic stary st_mode razem z nowym st_uid albo stary st_uid razem z nowym st_mode. fstatat() Wywolanie systemowe fstatat() jest ogolniejszym interfejsem do uzyskiwania dostepu do informacji o pliku, ktore moze wciaz zapewnic zachowanie identyczne do kazdego z wywolan stat(), lstat() i fstat(). Jesli sciezka path jest wzgledna, jest to interpretowane w odniesieniu do katalogu do ktorego odnosi sie deskryptor pliku dirfd (zamiast w odniesieniu do biezacego katalogu roboczego procesu wywolujacego, jak w stosunku do sciezek wzglednych robi to stat() i lstat()). Jesli path jest wzgledna a dirfd ma wartosc specjalna AT_FDCWD, to path jest interpretowana w odniesieniu do biezacego katalogu roboczego procesu wywolujacego (jak stat() i lstat()). Jesli sciezka path jest bezwzgledna, to dirfd jest ignorowane. flags moga wynosic albo 0, albo skladac sie z co najmniej jednego z ponizszych znacznikow zsumowanych bitowo (OR): AT_EMPTY_PATH (od Linuksa 2.6.39) Jesli path jest lancuchem pustym (lub NULL, od Linuksa 6.11), to dziala na pliku do ktorego odnosi sie dirfd (ktory mogl zostac pozyskany za pomoca znacznika O_PATH open(2)). W takim przypadku dirfd moze odnosic sie do kazdego typu pliku, nie tylko katalogu, a zachowanie fstatat() jest podobne do fstat(). Jesli dirfd wynosi AT_FDCWD, to wywolanie dziala w biezacym katalogu roboczym. Jest to opcja charakterystyczna dla Linuksa, prosze zdefiniowac _GNU_SOURCE, aby dostac sie do jej definicji. AT_NO_AUTOMOUNT (od Linuksa 2.6.38) Nie dokonuje automatycznego montowania skladowej terminala (,,basename") sciezki z path. Od Linuksa 3.1 znacznik ten jest ignorowany. Od Linuksa 4.11 znacznik ten jest implikowany. AT_SYMLINK_NOFOLLOW Jesli path jest dowiazaniem symbolicznym, nie podaza za nim, w zamian zwracajac informacje o samym dowiazaniu, jak lstat(). Domyslnie fstatat () podaza za dowiazaniami symbolicznymi, jak stat().) Wiecej informacji o potrzebie wprowadzenia fstatat() mozna znalezc w podreczniku openat(2). WARTOSC ZWRACANA Po pomyslnym zakonczeniu zwracane jest zero. Po bledzie zwracane jest -1 i ustawiane errno, wskazujac blad. BLEDY EACCES Brak uprawnien do przeszukiwania jednego z katalogow w sciezce zaczynajacej path (zob. tez path_resolution(7)). EBADF fd nie jest prawidlowym otwartym deskryptorem pliku. EBADF (fstatat()) path jest wzgledna, lecz dirfd nie wynosi ani AT_FDCWD, ani nie jest prawidlowym deskryptorem pliku. EFAULT Niepoprawny adres. EINVAL (fstatat()) Podano nieprawidlowa opcje we flags. ELOOP Podczas rozwiazywania sciezki napotkano zbyt wiele dowiazan symbolicznych. ENAMETOOLONG path jest zbyt dlugie. ENOENT Skladowa path nie istnieje lub jest wiszacym dowiazaniem symbolicznym. ENOENT path jest lancuchem pustym, a we flags nie podano AT_EMPTY_PATH. ENOMEM Brak pamieci (tj. pamieci jadra). ENOTDIR Skladowa sciezki path nie jest katalogiem. ENOTDIR (fstatat()) path jest wzgledna, a dirfd jest deskryptorem pliku odnoszacym sie do pliku, zamiast do katalogu. EOVERFLOW path lub fd odnosi sie do pliku, numeru i-wezla lub numeru blokow, ktorych rozmiar nie jest reprezentowalny w - odpowiednio - typie off_t, ino_t, blkcnt_t. Blad ten moze wystapic na przyklad wtedy, gdy aplikacja skompilowana na platformie 32-bitowej bez -D_FILE_OFFSET_BITS=64 wywola stat () na pliku, ktorego rozmiar jest wiekszy niz (1<<31)-1 bajtow. STANDARDY POSIX.1-2008. HISTORIA stat() fstat() lstat() SVr4, 4.3BSD, POSIX.1-2001. fstatat() POSIX.1-2008. Linux 2.6.16, glibc 2.4. Wedlug POSIX.1-2001 lstat() na dowiazaniu symbolicznym powinien zwrocic poprawne wartosci tylko w polu st_size i w czesci pola st_mode zwiazanej z typem pliku struktury stat. POSIX.1-2008 zaostrza te specyfikacje, wymagajac od lstat() zwracania poprawnych informacji we wszystkich polach z wyjatkiem bitow trybu w st_mode. Uzywanie pol st_blocks i st_blksize moze byc nieprzenosne (byly wprowadzone w BSD; interpretacje roznia sie zarowno miedzy systemami, jak i na jednym systemie, jesli uzyty jest zdalny system plikow montowany po NFS-ie). Roznice biblioteki C/jadra Z uplywem czasu, zwiekszanie rozmiarow struktury stat doprowadzilo do powstania trzech kolejnych wersji funkcji stat(): sys_stat() (slot __NR_oldstat), sys_newstat() (slot __NR_stat) i sys_stat64() (slot __NR_stat64) na platformach 32-bitowych takich jak i386. Pierwsze dwie wersje byly juz obecne w Linuksie 1.0 (choc z roznymi nazwami), ostatnia dodano w Linuksie 2.4. Podobne uwagi maja zastosowanie do fstat() i lstat(). Wewnatrzjadrowe wersje struktury stat, za pomoca ktorych jadro obsluguje te rozne wersje, to odpowiednio: __old_kernel_stat Oryginalna struktura z dosc waskimi polami i brakiem dopelnienia (wyrownania). stat Wieksze pole st_ino i dodane dopelnienie do roznych czesci struktury pozwalajace na pozniejsza rozbudowe. stat64 Jeszcze wieksze pole st_ino, wieksze pola st_uid i st_gid aby przyjac rozszerzone w Linuksie 2.4 UID-y i GID-y do 32 bitow i rozne inne poszerzenia pol oraz jeszcze wiecej dopelnien w strukturze (dopelnione bajty zostaly w koncu wykorzystane w Linuksie 2.6 po pojawieniu sie 32-bitowych identyfikatorow urzadzen oraz czesci nanosekundowej w polach znacznikow czasowych). Funkcja opakowujaca glibc stat() ukrywa te detale przed uzytkownikami, wywolujac najnowsza wersje wywolania systemowego udostepniana przez jadra i przepakowujac zwracane informacje, jesli jest to wymagane, dla starszych plikow wykonywalnych. Na wspolczesnych systemach 64-bitowych wszystko jest prostsze: istnieje jedno wywolanie systemowe stat(), a jadro wykorzystuje strukture stat zawierajaca pola o wystarczajacym rozmiarze. Wywolanie systemowe nizszego stopnia uzywane przez funkcje opakowujaca fstatat() glibc nazywa sie w rzeczywistosci fstatat64() lub, na niektorych architekturach, newfstatat(). PRZYKLADY Ponizszy program wywoluje lstat() i wypisuje wybrane pola zwrocone w strukturze stat: #include #include #include #include #include #include int main(int argc, char *argv[]) { struct stat sb; if (argc != 2) { fprintf(stderr, "Uzycie: %s \n", argv[0]); exit(EXIT_FAILURE); } if (lstat(argv[1], &sb) == -1) { perror("lstat"); exit(EXIT_FAILURE); } printf("ID urzadzenia: [%x,%x]\n", major(sb.st_dev), minor(sb.st_dev)); printf("Typ pliku: "); switch (sb.st_mode & S_IFMT) { case S_IFBLK: printf("urzadzenie blokowe\n"); break; case S_IFCHR: printf("urzadzenie znakowe\n"); break; case S_IFDIR: printf("katalog\n"); break; case S_IFIFO: printf("FIFO/potok\n"); break; case S_IFLNK: printf("dowiazanie symboliczne\n"); break; case S_IFREG: printf("zwykly plik\n"); break; case S_IFSOCK: printf("gniazdo\n"); break; default: printf("typ nieznany\n"); break; } printf("Numer i-wezla: %ju\n", (uintmax_t) sb.st_ino); printf("Tryb: %jo (osemkowo)\n", (uintmax_t) sb.st_mode); printf("Liczba dowiazan: %ju\n", (uintmax_t) sb.st_nlink); printf("Wlasciciel: UID=%ju GID=%ju\n", (uintmax_t) sb.st_uid, (uintmax_t) sb.st_gid); printf("Preferowany rozmiar bloku I/O: %jd bajtow\n", (intmax_t) sb.st_blksize); printf("Rozmiar bloku: %jd bajtow\n", (intmax_t) sb.st_size); printf("Liczba przydzielonych blokow: %jd\n", (intmax_t) sb.st_blocks); printf("Ostatnia zmiana stanu: %s", ctime(&sb.st_ctime)); printf("Ostatni dostep do pliku: %s", ctime(&sb.st_atime)); printf("Ostatnia zmiana pliku: %s", ctime(&sb.st_mtime)); exit(EXIT_SUCCESS); } ZOBACZ TAKZE ls(1), stat(1), access(2), chmod(2), chown(2), readlink(2), statx(2), utime(2), stat(3type), capabilities(7), inode(7), symlink(7) TLUMACZENIE Tlumaczenie niniejszej strony podrecznika: Przemek Borys , Robert Luberda i Michal Kulach Niniejsze tlumaczenie jest wolna dokumentacja. Blizsze informacje o warunkach licencji mozna uzyskac zapoznajac sie z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje sie ZADNEJ ODPOWIEDZIALNOSCI. Bledy w tlumaczeniu strony podrecznika prosimy zglaszac na adres listy dyskusyjnej . Linux man-pages 6.15 17 maja 2025 r. stat(2)