Manpages

NAZWA

stat, fstat, lstat, fstatat - pobieranie stanu pliku

SKŁADNIA

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

int stat(const char *pathname, struct stat *buf);
int fstat(int fd, struct stat *buf);
int lstat(const char *pathname, struct stat *buf);

#include <fcntl.h> /* Definicja stałych AT_* */
#include <sys/stat.h>

int fstatat(int dirfd, const char *pathname, struct stat *buf,
int flags);

Wymagane ustawienia makr biblioteki glibc (patrz feature_test_macros(7)):

lstat():

/* glibc 2.19 i wcześniejsze */ _BSD_SOURCE
|| /* Od glibc 2.20 */ _DEFAULT_SOURCE
|| _XOPEN_SOURCE >= 500
|| /* od glibc 2.10: */ _POSIX_C_SOURCE >= 200112L

fstatat():

Od glibc 2.10:

_POSIX_C_SOURCE >= 200809L

Przed glibc 2.10:

_ATFILE_SOURCE

OPIS

Funkcje te zwracają informacje o podanym pliku w buforze wskazanym przez buf. Do uzyskania tej informacji nie są wymagane prawa dostępu do samego pliku, lecz — w przypadku stat, fstatat() i lstat() — konieczne są prawa wykonywania (przeszukiwania) do wszystkich katalogów na prowadzącej do pliku ścieżce pathname.

stat() i fstatat() pobierają informacje o pliku wskazanym przez pathname; cechy wyróżniające fstatat() opisano poniżej.

lstat() jest identyczny z stat(), lecz w przypadku gdy pathname jest dowiązaniem symbolicznym, to zwraca informacje o samym dowiązaniu, a nie pliku, do którego się to dowiązanie odwołuje.

fstat() jest identyczny z stat(), z tym wyjątkiem, że plik o którym mają być pobrane informacje, 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) */
mode_t st_mode; /* tryb i typ pliku */
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 */

/* Od Linuksa 2.6 jądro obsługuje nanosekundową
rozdzielczość następujących pól znaczników czasu.
Szczegóły opisujące Linuksa w wersji starszej niż 2.6
znajdują się w rozdziale UWAGI */

struct timespec st_atim; /* czas ostatniego dostępu */
struct timespec st_mtim; /* czas ostatniej modyfikacji */
struct timespec st_ctim; /* czas ostatniej zmiany */
};

#define st_atime st_atim.tv_sec /* Kompatybilność wsteczna */
#define st_mtime st_mtim.tv_sec
#define st_ctime st_ctim.tv_sec
};

Uwaga: kolejność pól w strukturze stat różni się nieco w zależności od architektury. Dodatkowo, powyższa definicja nie pokazuje bajtów wyrównujących, które mogą być obecne pomiędzy niektórymi polami na różnych architekturach. Z tymi detalami można się zapoznać analizując glibc i kod źródłowy jądra.

Uwaga: Dla zachowania wydajności i prostoty, różne pola w strukturze stat mogą zawierać stany z różnych momentów wykonywania wywołania systemowego. Przykładowo, jeśli st_mode lub st_uid zostanie zmieniony przez inny proces za pomocą wywołania chmod(2) lub chown(2), stat() może zwrócić stary st_mode razem z nowym st_uid albo stary st_uid razem z nowym st_mode.

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.).

POSIX odnosi się do bitów st_mode odpowiadających masce S_IFMT (zob. poniżej) jako typu pliku, 12 bitów odpowiadających masce 07777 jako bitów trybu pliku i najmniej znaczących 9 bitów (0777) jako bitów uprawnień pliku.

Zdefiniowane są następujące wartości masek do typu pliku z pola st_mode:

Dlatego, aby sprawdzić czy plik jest (przykładowo) zwykłym plikiem można napisać:

stat(pathname, &sb);
if ((sb.st_mode & S_IFMT) == S_IFREG) {
/* Obsługa zwykłego pliku */
}

Ponieważ testy w powyższej postaci są popularne, dodatkowe makra są zdefiniowane przez POSIX w celu umożliwienia sprawdzenia typu pliku w st_mode w spójniejszej formie:

Poprzedni przykład kodu można dlatego przepisać w następujący sposób:

stat(pathname, &sb);
if (S_ISREG(sb.st_mode)) {
/* Obsługa zwykłego pliku */
}

Definicje większości powyższych makr sprawdzających typ pliku są udostępniane, jeśli tylko któraś z następujących funkcji makd sprawdzających jest zdefiniowana: _BSD_SOURCE (w 2.19 i wcześniejszych), _SVID_SOURCE (w glibc 2.19 i wcześniejszych) lub _DEFAULT_SOURCE (w glibc 2.20 i późniejszych). Dodatkowo, definicje wszystkich powyższych makr z wyjątkiem S_IFSOCK i S_ISSOCK() są udostępniane jeśli zdefiniowano _XOPEN_SOURCE. Zdefiniowanie S_IFSOCK można również uwidocznić definiując _XOPEN_SOURCE z wartością większą lub równą 500.

Zdefiniowanie S_ISSOCK() jest uwidocznione, jeśli zdefiniowano dowolne z następujących makr sprawdzających: _BSD_SOURCE (w 2.19 i wcześniejszych), _DEFAULT_SOURCE (w glibc 2.20 i późniejszych), _XOPEN_SOURCE z wartością większą lub równą 500 lub _POSIX_C_SOURCE z wartością większą lub równą 200112L.

Zdefiniowane są następujące wartości masek do części określającej tryb pliku w polu st_mode:

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.

fstatat()
Wywołanie systemowe fstatat() działa w ten sam sposób co stat(), z wyjątkiem opisanych tu różnic.

Jeśli ścieżka podana w pathname jest względna, jest to interpretowane w odniesieniu do katalogu do którego odnosi się deskryptor pliku dirfd (zamiast w odniesieniu do bieżącego katalogu roboczego procesu wywołującego, jak w stosunku do ścieżek względnych robi to stat()).

Jeśli pathname jest względna a dirfd ma wartość specjalną AT_FDCWD, to pathname jest interpretowana w odniesieniu do bieżącego katalogu roboczego procesu wywołującego (jak stat()).

If ścieżka pathname jest bezwzględna, to dirfd jest ignorowane.

flags mogą wynosić albo 0, albo składać się z co najmniej jednej z poniższych opcji połączonych operatorem OR:
AT_EMPTY_PATH (od Linuksa 2.6.39)

Jeśli pathname jest łańcuchem pustym, to działa na pliku do którego odnosi się dirfd (który mógł zostać pozyskany za pomocą flagi O_PATH open(2)). Jeśli dirfd wynosi AT_FDCWD, to wywołujący działa w bieżącym katalogu roboczym. W takim przypadku dirfd może odnosić się do każdego typu pliku, nie tylko katalogu. Jest to opcja charakterystyczna dla Linuksa, proszę zdefiniować _GNU_SOURCE, aby dostać się do jej definicji.