1INODE(7) Linux Programmer's Manual INODE(7)
2
6 inode - file inode information
7
9 Each file has an inode containing metadata about the file. An applica‐
10 tion can retrieve this metadata using stat(2) (or related calls), which
11 returns a stat structure, or statx(2), which returns a statx structure.
12 The following is a list of the information typically found in, or asso‐
14 ciated with, the file inode, with the names of the corresponding struc‐
15 ture fields returned by stat(2) and statx(2):
16 Device where inode resides
18 stat.st_dev; statx.stx_dev_minor and statx.stx_dev_major
19 Each inode (as well as the associated file) resides in a
21 filesystem that is hosted on a device. That device is identi‐
22 fied by the combination of its major ID (which identifies the
23 general class of device) and minor ID (which identifies a spe‐
24 cific instance in the general class).
25 Inode number
27 stat.st_ino; statx.stx_ino
28 Each file in a filesystem has a unique inode number. Inode num‐
30 bers are guaranteed to be unique only within a filesystem (i.e.,
31 the same inode numbers may be used by different filesystems,
32 which is the reason that hard links may not cross filesystem
33 boundaries). This field contains the file's inode number.
34 File type and mode
36 stat.st_mode; statx.stx_mode
37 See the discussion of file type and mode, below.
39 Link count
41 stat.st_nlink; statx.stx_nlink
42 This field contains the number of hard links to the file. Addi‐
44 tional links to an existing file are created using link(2).
45 User ID
47 st_uid stat.st_uid; statx.stx_uid
48 This field records the user ID of the owner of the file. For
50 newly created files, the file user ID is the effective user ID
51 of the creating process. The user ID of a file can be changed
52 using chown(2).
53 Group ID
55 stat.st_gid; statx.stx_gid
56 The inode records the ID of the group owner of the file. For
58 newly created files, the file group ID is either the group ID of
59 the parent directory or the effective group ID of the creating
60 process, depending on whether or not the set-group-ID bit is set
61 on the parent directory (see below). The group ID of a file can
62 be changed using chown(2).
63 Device represented by this inode
65 stat.st_rdev; statx.stx_rdev_minor and statx.stx_rdev_major
66 If this file (inode) represents a device, then the inode records
68 the major and minor ID of that device.
69 File size
71 stat.st_size; statx.stx_size
72 This field gives the size of the file (if it is a regular file
74 or a symbolic link) in bytes. The size of a symbolic link is
75 the length of the pathname it contains, without a terminating
76 null byte.
77 Preferred block size for I/O
79 stat.st_blksize; statx.stx_blksize
80 This field gives the "preferred" blocksize for efficient
82 filesystem I/O. (Writing to a file in smaller chunks may cause
83 an inefficient read-modify-rewrite.)
84 Number of blocks allocated to the file
86 stat.st_blocks; statx.stx_size
87 This field indicates the number of blocks allocated to the file,
89 512-byte units, (This may be smaller than st_size/512 when the
90 file has holes.)
91 The POSIX.1 standard notes that the unit for the st_blocks mem‐
93 ber of the stat structure is not defined by the standard. On
94 many implementations it is 512 bytes; on a few systems, a dif‐
95 ferent unit is used, such as 1024. Furthermore, the unit may
96 differ on a per-filesystem basis.
97 Last access timestamp (atime)
99 stat.st_atime; statx.stx_atime
100 This is the file's last access timestamp. It is changed by file
102 accesses, for example, by execve(2), mknod(2), pipe(2),
103 utime(2), and read(2) (of more than zero bytes). Other inter‐
104 faces, such as mmap(2), may or may not update the atime time‐
105 stamp
106 Some filesystem types allow mounting in such a way that file
108 and/or directory accesses do not cause an update of the atime
109 timestamp. (See noatime, nodiratime, and relatime in mount(8),
110 and related information in mount(2).) In addition, the atime
111 timestamp is not updated if a file is opened with the O_NOATIME
112 flag; see open(2).
113 File creation (birth) timestamp (btime)
115 (not returned in the stat structure); statx.stx_btime
116 The file's creation timestamp. This is set on file creation and
118 not changed subsequently.
119 The btime timestamp was not historically present on UNIX systems
121 and is not currently supported by most Linux filesystems.
122 Last modification timestamp (mtime)
124 stat.st_atime; statx.stx_mtime
125 This is the file's last modification timestamp. It is changed
127 by file modifications, for example, by mknod(2), truncate(2),
128 utime(2), and write(2) (of more than zero bytes). Moreover, the
129 mtime timestamp of a directory is changed by the creation or
130 deletion of files in that directory. The mtime timestamp is not
131 changed for changes in owner, group, hard link count, or mode.
132 Last status change timestamp (ctime)
134 stat.st_ctime; statx.stx_ctime
135 This is the file's last status change timestamp. It is changed
137 by writing or by setting inode information (i.e., owner, group,
138 link count, mode, etc.).
139 Nanosecond timestamps are supported on XFS, JFS, Btrfs, and ext4 (since
141 Linux 2.6.23). Nanosecond timestamps are not supported in ext2, ext3,
142 and Reiserfs. On filesystems that do not support subsecond timestamps,
143 the nanosecond fields in the stat and statx structures are returned
144 with the value 0.
145 The file type and mode
147 The stat.st_mode field (for statx(2), the statx.stx_mode field) con‐
148 tains the file type and mode.
149 POSIX refers to the stat.st_mode bits corresponding to the mask S_IFMT
151 (see below) as the file type, the 12 bits corresponding to the mask
152 07777 as the file mode bits and the least significant 9 bits (0777) as
153 the file permission bits.
154 The following mask values are defined for the file type:
156 S_IFMT 0170000 bit mask for the file type bit field
158 S_IFSOCK 0140000 socket
160 S_IFLNK 0120000 symbolic link
161 S_IFREG 0100000 regular file
162 S_IFBLK 0060000 block device
163 S_IFDIR 0040000 directory
164 S_IFCHR 0020000 character device
165 S_IFIFO 0010000 FIFO
166 Thus, to test for a regular file (for example), one could write:
168 stat(pathname, &sb);
170 if ((sb.st_mode & S_IFMT) == S_IFREG) {
171 /* Handle regular file */
172 }
173 Because tests of the above form are common, additional macros are
175 defined by POSIX to allow the test of the file type in st_mode to be
176 written more concisely:
177 S_ISREG(m) is it a regular file?
179 S_ISDIR(m) directory?
181 S_ISCHR(m) character device?
183 S_ISBLK(m) block device?
185 S_ISFIFO(m) FIFO (named pipe)?
187 S_ISLNK(m) symbolic link? (Not in POSIX.1-1996.)
189 S_ISSOCK(m) socket? (Not in POSIX.1-1996.)
191 The preceding code snippet could thus be rewritten as:
193 stat(pathname, &sb);
195 if (S_ISREG(sb.st_mode)) {
196 /* Handle regular file */
197 }
198 The definitions of most of the above file type test macros are provided
200 if any of the following feature test macros is defined: _BSD_SOURCE (in
201 glibc 2.19 and earlier), _SVID_SOURCE (in glibc 2.19 and earlier), or
202 _DEFAULT_SOURCE (in glibc 2.20 and later). In addition, definitions of
203 all of the above macros except S_IFSOCK and S_ISSOCK() are provided if
204 _XOPEN_SOURCE is defined.
205 The definition of S_IFSOCK can also be exposed either by defining
207 _XOPEN_SOURCE with a value of 500 or greater or (since glibc 2.24) by
208 defining both _XOPEN_SOURCE and _XOPEN_SOURCE_EXTENDED.
209 The definition of S_ISSOCK() is exposed if any of the following feature
211 test macros is defined: _BSD_SOURCE (in glibc 2.19 and earlier),
212 _DEFAULT_SOURCE (in glibc 2.20 and later), _XOPEN_SOURCE with a value
213 of 500 or greater, _POSIX_C_SOURCE with a value of 200112L or greater,
214 or (since glibc 2.24) by defining both _XOPEN_SOURCE and
215 _XOPEN_SOURCE_EXTENDED.
216 The following mask values are defined for the file mode component of
218 the st_mode field:
219 S_ISUID 04000 set-user-ID bit
221 S_ISGID 02000 set-group-ID bit (see below)
222 S_ISVTX 01000 sticky bit (see below)
223 S_IRWXU 00700 owner has read, write, and execute permission
225 S_IRUSR 00400 owner has read permission
226 S_IWUSR 00200 owner has write permission
227 S_IXUSR 00100 owner has execute permission
228 S_IRWXG 00070 group has read, write, and execute permission
230 S_IRGRP 00040 group has read permission
231 S_IWGRP 00020 group has write permission
232 S_IXGRP 00010 group has execute permission
233 S_IRWXO 00007 others (not in group) have read, write, and
235 execute permission
236 S_IROTH 00004 others have read permission
237 S_IWOTH 00002 others have write permission
238 S_IXOTH 00001 others have execute permission
239 The set-group-ID bit (S_ISGID) has several special uses. For a direc‐
241 tory, it indicates that BSD semantics is to be used for that directory:
242 files created there inherit their group ID from the directory, not from
243 the effective group ID of the creating process, and directories created
244 there will also get the S_ISGID bit set. For a file that does not have
245 the group execution bit (S_IXGRP) set, the set-group-ID bit indicates
246 mandatory file/record locking.
247 The sticky bit (S_ISVTX) on a directory means that a file in that
249 directory can be renamed or deleted only by the owner of the file, by
250 the owner of the directory, and by a privileged process.
251
253 If you need to obtain the definition of the blkcnt_t or blksize_t types
254 from <sys/stat.h>, then define _XOPEN_SOURCE with the value 500 or
255 greater (before including any header files).
256 POSIX.1-1990 did not describe the S_IFMT, S_IFSOCK, S_IFLNK, S_IFREG,
258 S_IFBLK, S_IFDIR, S_IFCHR, S_IFIFO, S_ISVTX constants, but instead
259 specified the use of the macros S_ISDIR(), and so on. The S_IF* con‐
260 stants are present in POSIX.1-2001 and later.
261 The S_ISLNK() and S_ISSOCK() macros were not in POSIX.1-1996, but both
263 are present in POSIX.1-2001; the former is from SVID 4, the latter from
264 SUSv2.
265 UNIX V7 (and later systems) had S_IREAD, S_IWRITE, S_IEXEC, where POSIX
267 prescribes the synonyms S_IRUSR, S_IWUSR, S_IXUSR.
268
270 For pseudofiles that are autogenerated by the kernel, the file size
271 (stat.st_size; statx.stx_size) reported by the kernel is not accurate.
272 For example, the value 0 is returned for many files under the /proc
273 directory, while various files under /sys report a size of 4096 bytes,
274 even though the file content is smaller. For such files, one should
275 simply try to read as many bytes as possible (and append '\0' to the
276 returned buffer if it is to be interpreted as a string). st_atimensec.
277
279 stat(1), stat(2), statx(2), symlink(7)
280
282 This page is part of release 4.16 of the Linux man-pages project. A
283 description of the project, information about reporting bugs, and the
284 latest version of this page, can be found at
285 https://www.kernel.org/doc/man-pages/.
286Linux 2017-09-15 INODE(7)