1STAT(2) Linux Programmer's Manual STAT(2)
2
6 stat, fstat, lstat, fstatat - get file status
7
9 #include <sys/types.h>
10 #include <sys/stat.h>
11 #include <unistd.h>
12 int stat(const char *pathname, struct stat *statbuf);
14 int fstat(int fd, struct stat *statbuf);
15 int lstat(const char *pathname, struct stat *statbuf);
16 #include <fcntl.h> /* Definition of AT_* constants */
18 #include <sys/stat.h>
19 int fstatat(int dirfd, const char *pathname, struct stat *statbuf,
21 int flags);
22 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
24 lstat():
26 /* glibc 2.19 and earlier */ _BSD_SOURCE
27 || /* Since glibc 2.20 */ _DEFAULT_SOURCE
28 || _XOPEN_SOURCE >= 500
29 || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L
30 fstatat():
32 Since glibc 2.10:
33 _POSIX_C_SOURCE >= 200809L
34 Before glibc 2.10:
35 _ATFILE_SOURCE
36
38 These functions return information about a file, in the buffer pointed
39 to by statbuf. No permissions are required on the file itself, but—in
40 the case of stat(), fstatat(), and lstat()—execute (search) permission
41 is required on all of the directories in pathname that lead to the
42 file.
43 stat() and fstatat() retrieve information about the file pointed to by
45 pathname; the differences for fstatat() are described below.
46 lstat() is identical to stat(), except that if pathname is a symbolic
48 link, then it returns information about the link itself, not the file
49 that the link refers to.
50 fstat() is identical to stat(), except that the file about which infor‐
52 mation is to be retrieved is specified by the file descriptor fd.
53 The stat structure
55 All of these system calls return a stat structure, which contains the
56 following fields:
57 struct stat {
59 dev_t st_dev; /* ID of device containing file */
60 ino_t st_ino; /* Inode number */
61 mode_t st_mode; /* File type and mode */
62 nlink_t st_nlink; /* Number of hard links */
63 uid_t st_uid; /* User ID of owner */
64 gid_t st_gid; /* Group ID of owner */
65 dev_t st_rdev; /* Device ID (if special file) */
66 off_t st_size; /* Total size, in bytes */
67 blksize_t st_blksize; /* Block size for filesystem I/O */
68 blkcnt_t st_blocks; /* Number of 512B blocks allocated */
69 /* Since Linux 2.6, the kernel supports nanosecond
71 precision for the following timestamp fields.
72 For the details before Linux 2.6, see NOTES. */
73 struct timespec st_atim; /* Time of last access */
75 struct timespec st_mtim; /* Time of last modification */
76 struct timespec st_ctim; /* Time of last status change */
77 #define st_atime st_atim.tv_sec /* Backward compatibility */
79 #define st_mtime st_mtim.tv_sec
80 #define st_ctime st_ctim.tv_sec
81 };
82 Note: the order of fields in the stat structure varies somewhat across
84 architectures. In addition, the definition above does not show the
85 padding bytes that may be present between some fields on various archi‐
86 tectures. Consult the glibc and kernel source code if you need to know
87 the details.
88 Note: for performance and simplicity reasons, different fields in the
90 stat structure may contain state information from different moments
91 during the execution of the system call. For example, if st_mode or
92 st_uid is changed by another process by calling chmod(2) or chown(2),
93 stat() might return the old st_mode together with the new st_uid, or
94 the old st_uid together with the new st_mode.
95 The fields in the stat structure are as follows:
97 st_dev This field describes the device on which this file resides.
99 (The major(3) and minor(3) macros may be useful to decompose the
100 device ID in this field.)
101 st_ino This field contains the file's inode number.
103 st_mode
105 This field contains the file type and mode. See inode(7) for
106 further information.
107 st_nlink
109 This field contains the number of hard links to the file.
110 st_uid This field contains the user ID of the owner of the file.
112 st_gid This field contains the ID of the group owner of the file.
114 st_rdev
116 This field describes the device that this file (inode) repre‐
117 sents.
118 st_size
120 This field gives the size of the file (if it is a regular file
121 or a symbolic link) in bytes. The size of a symbolic link is
122 the length of the pathname it contains, without a terminating
123 null byte.
124 st_blksize
126 This field gives the "preferred" block size for efficient
127 filesystem I/O.
12