STAT(2)

ИМЯ
stat, fstat, lstat - получить статус файла

КРАТКАЯ СВОДКА
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>

int stat(const char *file_name, struct stat *buf);
int fstat(int filedes, struct stat *buf);
int lstat(const char *file_name, struct stat *buf);

ОПИСАНИЕ

Эти функции возвращают информацию об указанном файле. Вам не требуется иметь права доступа к файлу, чтобы получить эту информацию, хотя всё же требуются права поиска во всех каталогах, которые находятся по пути к файлу.

stat возвращает информацию о файле, заданном с помощью file_name и заполняет буфер buf. lstat идентична stat, но в случае, если обрабатывается символьная ссылка, то возвращается информация о самой ссылке, а не о файле, на который она ссылается. fstat идентична stat, но вместо file_name возвращается информация о filedes (который возвращается системным вызовом open(2)).

Все эти функции возвращают структуру stat, которая содержит такие поля:

    struct stat {
        dev_t         st_dev;      /* устройство */
        ino_t         st_ino;      /* inode */
        mode_t        st_mode;     /* режим доступа */
        nlink_t       st_nlink;    /* количество жестких ссылок */
        uid_t         st_uid;      /* ID пользователя-владельца */
        gid_t         st_gid;      /* ID группы-владельца */
        dev_t         st_rdev;     /* тип устройства */
                                   /* (если это устройство) */
        off_t         st_size;     /* общий размер в байтах */
        unsigned long st_blksize;  /* размер блока ввода-вывода */
                                   /* в файловой системе */
        unsigned long st_blocks;   /* количество выделенных блоков */
        time_t        st_atime;    /* время последнего доступа */
        time_t        st_mtime;    /* время последней модификации */
        time_t        st_ctime;    /* время последнего изменения */
    };

Значение st_size дает размер файла в байтах (если это обычный файл или символьная ссылка). Размер символьной ссылки равен длине пути, который она содержит, без концевого NUL.

Значение st_blocks задает размер файла в 512-байтных блоках. Значение st_blksize задает "предпочтительный" размер блока для эффективного ввода-вывода на файловой системе. (Запись в файл более мелкими порциями может привести к неэффективному чтению-изменению-повторной записи).

Не все файловые системы под Linux реализуют все метки времени. Некоторые файловые системы позволяют монтировать так, что обращения к файлам не изменяют поле st_atime. (См. 'noatime' в mount(8). Поле st_atime изменяется при доступе к файлу, например, при exec(2), mknod(2), pipe(2), utime(2) и read(2) (если прочитано больше нуля байт). Другие функции, например, mmap(2), могут изменять, а могу и не изменять st_atime. Поле st_mtime изменяется при модификациях файла, например, при mknod(2), truncate(2), utime(2) и write(2) (если записано больше нуля байт). Более того, поле st_mtime каталога изменяется при создании и удалении файлов в этом каталоге. Поле st_mtime не изменяется при изменении владельца, группы, количества жестких ссылок или режима доступа. Поле st_ctime изменяется при записи или установке информации об inode (владельце, группе, количеству ссылок, режиме и т. д.).

Нижеследующие макросы POSIX определены для проверки типа файлов:

    S_ISREG(m)
        является ли обычным файлом?

    S_ISDIR(m)
        каталогом?

    S_ISCHR(m)
        символьным устройством?

    S_ISBLK(m)
        блочным устройством?

    S_ISFIFO(m)
        каналом FIFO?

    S_ISLNK(m)
        символической ссылкой? (Этого флага нет в POSIX.1-1996.)

    S_ISSOCK(m)
        сокетом? (Этого флага нет в POSIX.1-1996.)

Нижеследующие флаги определены для поля st_mode:

S_IFMT | 0170000 | битовая маска для полей типа файла
S_IFSOCK | 0140000 | сокет
S_IFLNK | 0120000 | символическая ссылка
S_IFREG | 0100000 | обычный файл
S_IFBLK | 0060000 | блочное устройство
S_IFDIR | 0040000 | каталог
S_IFCHR | 0020000 | символьное устройство
S_IFIFO | 0010000 | канал FIFO
S_ISUID | 0004000 | бит setuid
S_ISGID | 0002000 | бит setgid (смотри ниже)
S_ISVTX | 0001000 | бит липкости (смотри ниже)
S_IRWXU | 00700 | маска для прав доступа пользователя
S_IRUSR | 00400 | пользователь имеет право чтения
S_IWUSR | 00200 | пользователь имеет право записи
S_IXUSR | 00100 | пользователь имеет право выполнения
S_IRWXG | 00070 | маска для прав доступа группы
S_IRGRP | 00040 | группа имеет права чтения
S_IWGRP | 00020 | группа имеет права записи
S_IXGRP | 00010 | группа имеет права выполнения
S_IRWXO | 00007 | маска прав доступа всех прочих (не находящихся в группе)
S_IROTH | 00004 | все прочие имеют права чтения
S_IWOTH | 00002 | все прочие имеют права записи
S_IXOTH | 00001 | все прочие имеют права выполнения

Бит setgid (S_ISGID) имеет несколько специальных применений: На каталоге он означает, что для этого каталога используется семантика BSD: файлы, создаваемые в нем, наследуют свою группу-владельца от этого каталога, а не от фактической группы-владельца процесса, создавшего файл, а на подкаталогах, которые созданы в этом каталоге, также будет установлен бит S_ISGID. Для файла, которые не имеет бит выполнения группой (S_IXGRP), бит setgid означает жесткую блокировку файла/записей.

Бит "липкости" (S_ISVTX) на каталоге означает, что файлы в этом каталоге могут быть удалены или переименованы только владельцем файла, владельцем каталога, и суперпользователем.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
В случае успеха возвращается ноль. При ошибке возвращается -1, а errno устанавливается должным образом.

ОШИБКИ

EBADF
    Плохой файловый дескриптор filedes.

ENOENT
    Компонент пути file_name не существует, или путь является пустой строкой.

ENOTDIR
    Компонент пути не является каталогом.

ELOOP
    При поиске файла встретилось слишком много символических ссылок.

EFAULT
    Плохой адрес.

EACCES
    Доступ запрещен.

ENOMEM
    Ядру не хватило памяти.

ENAMETOOLONG
    Имя слишком длинное.

СООТВЕТСТВИЕ СТАНДАРТАМ
Системные вызовы stat и fstat соответствуют SVr4, SVID, POSIX, X/OPEN, BSD 4.3. Системный вызов lstat соответствует 4.3BSD и SVr4. SVr4 документирует дополнительные коды ошибок fstat: EINTR, ENOLINK и EOVERFLOW. SVr4 документирует дополнительные коды ошибок stat и lstat: EACCES, EINTR, EMULTIHOP, ENOLINK и EOVERFLOW. Использование полей st_blocks и st_blksize может быть менее переносимо. (Эти поля появились в BSD и не указана в POSIX. Их интерпретация различается на разных системах и, вероятно, даже на одной и той же системе, если есть смонтированные файловые системы NFS).

POSIX не описывает биты S_IFMT, S_IFSOCK, S_IFLNK, S_IFREG, S_IFBLK, S_IFDIR, S_IFCHR, S_IFIFO, S_ISVTX, но вместо этого требует использовать макросы S_ISDIR() и т. п. Макросы S_ISLNK и S_ISSOCK не упомянуты в POSIX.1-1996, но будут присутствовать в следующем стандарте POSIX; первый из них взят из SVID 4v2, второй -- из SUSv2.

Unix V7 (и более поздние системы) имеют S_IREAD, S_IWRITE, S_IEXEC, тогда как POSIX требует присутствия синонимов S_IRUSR, S_IWUSR, S_IXUSR.

ДРУГИЕ СИСТЕМЫ
Значения, которые использовались или используются на различных системах:

hex | имя | ls | oct | описание
f000 | S_IFMT |  | 170000 | маска типа файла
0000 |  |  | 000000 | SCO: недействующий inode
 |  |  |  | BSD: неизвестный тип
 |  |  |  | в SVID-v2 и XPG2 как 0, так и 0100000
 |  |  |  | означают обычный файл
1000 | S_IFIFO | p| | 010000 | именованный канал FIFO
2000 | S_IFCHR | c | 020000 | символьной устройство (V7)
3000 | S_IFMPC |  | 030000 | мультиплексированное символьное
 |  |  |  | устройство (V7)
4000 | S_IFDIR | d/ | 040000 | каталог (V7)
5000 | S_IFNAM |  | 050000 | XENIX: именованный специальный файл с
 |  |  |  | двумя подтипами, с разными значениями
 |  |  |  | st_rdev (1 и 2)
0001 | S_INSEM | s | 000001 | XENIX семафор, подтип IFNAM
0002 | S_INSHD | m | 000002 | XENIX разделяемые данные, подтип IFNAM
6000 | S_IFBLK | b | 060000 | блочное устройство (V7)
7000 | S_IFMPB |  | 070000 | мультиплексированное блочное
 |  |  |  | устройство (V7)
8000 | S_IFREG | - | 100000 | обычный файл (V7)
9000 | S_IFCMP |  | 110000 | VxFS: компрессированный файл
9000 | S_IFNWK | n | 110000 | сетевое устройство (HP-UX)
a000 | S_IFLNK | l@ | 120000 | символическая ссылка (BSD)
b000 | S_IFSHAD |  | 130000 | Solaris: теневой inode для ACL
 |  |  |  | (не виден пользовательскими
 |  |  |  | процессами)
c000 | S_IFSOCK | s= | 140000 | сокет (BSD; также "S_IFSOC" on VxFS)
d000 | S_IFDOOR | D> | 150000 | Solaris: door
e000 | S_IFWHT | w% | 160000 | BSD whiteout (не используется для inode'ов)
0200 | S_ISVTX |  | 001000 | бит липкости: сохранить код
 |  |  |  | программы в файле подкачки даже после
 |  |  |  | использования (V7)
 |  |  |  | зарезервировано (SVID-v2)
 |  |  |  | На не-каталогах: не кэшировать этот
 |  |  |  | файл (SunOS)
 |  |  |  | На каталогах: флаг ограниченного
 |  |  |  | удаления (SVID-v4.2)
0400 | S_ISGID |  | 002000 | установить идентификатор группы при
 |  |  |  | выполнении (V7)
 |  |  |  | для каталогов: использовать семантику
 |  |  |  | BSD для установки группы-владельца
0400 | S_ENFMT |  | 002000 | жесткая блокировка файлов в стиле SysV
 |  |  |  | (делит функции c S_ISGID)
0800 | S_ISUID |  | 004000 | установить идентификатор пользователя
 |  |  |  | при выполнении (V7)
0800 | S_CDF |  | 004000 | каталог является файлом, зависящим от контекста (HP-UX)
Липкие команды появились в Version 32V AT&T UNIX.

СМОТРИ ТАКЖЕ
chmod(2), chown(2), readlink(2), utime(2)

ПЕРЕВОД
Copyright (C) Alexey Mahotkin <alexm@hsys.msk.ru> 1999-2001