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 pathname, struct stat *restrict statbuf); int fstat(int fd, struct stat *statbuf); int lstat(const char *restrict pathname, struct stat *restrict statbuf); #include /* Definicja stalych AT_* */ #include int fstatat(int dirfd, const char *restrict pathname, 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 pathname. stat() i fstatat() pobieraja informacje o pliku wskazanym przez pathname; cechy wyrozniajace fstatat() opisano ponizej. lstat() jest identyczny z stat(), lecz w przypadku gdy pathname 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 podana w pathname 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 pathname jest wzgledna a dirfd ma wartosc specjalna AT_FDCWD, to pathname jest interpretowana w odniesieniu do biezacego katalogu roboczego procesu wywolujacego (jak stat() i lstat()). Jesli sciezka pathname 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) If pathname 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 (od Linuksa 2.6.38) Nie dokonuje automatycznego montowania skladowej terminala (,,basename") sciezki z pathname. Od Linuksa 3.1 znacznik ten jest ignorowany. Od Linuksa 4.11 znacznik ten jest implikowany. AT_SYMLINK_NOFOLLOW Jesli pathname 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 pathname (zob. tez path_resolution(7)). EBADF fd nie jest prawidlowym otwartym deskryptorem pliku. EBADF (fstatat()) pathname jest wzgledne, 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 Sciezka pathname jest zbyt dluga. ENOENT Skladnik pathname nie istnieje lub jest wiszacym dowiazaniem symbolicznym. ENOENT pathname jest lancuchem pustym, a we flags nie podano AT_EMPTY_PATH. ENOMEM Brak pamieci (tj. pamieci jadra). ENOTDIR Skladnik sciezki pathname nie jest katalogiem. ENOTDIR (fstatat()) pathname jest wzgledna, a dirfd jest deskryptorem pliku odnoszacym sie do pliku, zamiast do katalogu. EOVERFLOW pathname 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 Autorami polskiego tlumaczenia niniejszej strony podrecznika sa: 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.12 9 stycznia 2025 r. stat(2)