stat(2) System Calls Manual stat(2) NAZWA stat, fstat, lstat, fstatat - pobieranie stanu 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() is identical to stat(), except that if pathname is a symbolic link, then it returns information about the link itself, not the file that the link refers to. fstat() jest identyczny z stat(), z tym wyjatkiem, ze plik o ktorym maja byc pobrane informacje, jest okreslony przez deskryptor pliku fd. The stat structure All of these system calls return a stat structure (see 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() The fstatat() system call is a more general interface for accessing file information which can still provide exactly the behavior of each of stat(), lstat(), and 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 jednej z ponizszych opcji polaczonych operatorem OR: AT_EMPTY_PATH (od Linuksa 2.6.39) If pathname is an empty string, 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) Don't automount the terminal ("basename") component of pathname. Since Linux 3.1 this flag is ignored. Since Linux 4.11 this flag is implied. AT_SYMLINK_NOFOLLOW Jesli pathname jest dowiazaniem symbolicznym nie podaza za nim, w zamian zwraca 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 jest errno wskazujac blad. BLEDY EACCES Brak uprawnien do przeszukiwania jednego z katalogow w sciezce zaczynajacej pathname. (Patrz takze path_resolution(7)). EBADF fd nie jest prawidlowym otwartym deskryptorem pliku. EBADF (fstatat()) pathname is relative but dirfd is neither AT_FDCWD nor a valid file descriptor. EFAULT Niepoprawny adres. EINVAL (fstatat()) Podano nieprawidlowa opcje w 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 is an empty string and AT_EMPTY_PATH was not specified in flags. 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, "Usage: %s \n", argv[0]); exit(EXIT_FAILURE); } if (lstat(argv[1], &sb) == -1) { perror("lstat"); exit(EXIT_FAILURE); } printf("ID of containing device: [%x,%x]\n", major(sb.st_dev), minor(sb.st_dev)); printf("File type: "); switch (sb.st_mode & S_IFMT) { case S_IFBLK: printf("block device\n"); break; case S_IFCHR: printf("character device\n"); break; case S_IFDIR: printf("directory\n"); break; case S_IFIFO: printf("FIFO/pipe\n"); break; case S_IFLNK: printf("symlink\n"); break; case S_IFREG: printf("regular file\n"); break; case S_IFSOCK: printf("socket\n"); break; default: printf("unknown?\n"); break; } printf("I-node number: %ju\n", (uintmax_t) sb.st_ino); printf("Mode: %jo (octal)\n", (uintmax_t) sb.st_mode); printf("Link count: %ju\n", (uintmax_t) sb.st_nlink); printf("Ownership: UID=%ju GID=%ju\n", (uintmax_t) sb.st_uid, (uintmax_t) sb.st_gid); printf("Preferred I/O block size: %jd bytes\n", (intmax_t) sb.st_blksize); printf("File size: %jd bytes\n", (intmax_t) sb.st_size); printf("Blocks allocated: %jd\n", (intmax_t) sb.st_blocks); printf("Last status change: %s", ctime(&sb.st_ctime)); printf("Last file access: %s", ctime(&sb.st_atime)); printf("Last file modification: %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.06 31 pazdziernika 2023 r. stat(2)