2 .\" Copyright (c) 2017 Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .TH INODE 7 2017-07-13 "Linux" "Linux Programmer's Manual"
28 inode \- file inode information
30 Each file has an inode containing metadata about the file.
31 An application can retrieve this metadata using
33 (or related calls), which returns a
41 The following is a list of the information typically found in,
42 or associated with, the file inode,
43 with the names of the corresponding structure fields returned by
48 Device where inode resides
49 \fIstat.st_dev\fP; \fIstatx.stx_dev_minor\fP and \fIstatx.stx_dev_major\fP
51 Each inode (as well as the associated file) resides in a filesystem
52 that is hosted on a device.
53 That device is identified by the combination of its major ID
54 (which identifies the general class of device)
55 and minor ID (which identifies a specific instance in the general class).
58 \fIstat.st_ino\fP; \fIstatx.stx_ino\fP
60 Each file in a filesystem has a unique inode number.
61 Inode numbers are guaranteed to be unique only within a filesystem
62 (i.e., the same inode numbers may be used by different filesystems,
63 which is the reason that hard links may not cross filesystem boundaries).
64 This field contains the file's inode number.
67 \fIstat.st_mode\fP; \fIstatx.stx_mode\fP
69 See the discussion of file type and mode, below.
72 \fIstat.st_nlink\fP; \fIstatx.stx_nlink\fP
74 This field contains the number of hard links to the file.
75 Additional links to an existing file are created using
80 \fIstat.st_uid\fP; \fIstatx.stx_uid\fP
82 This field records the user ID of the owner of the file.
83 For newly created files,
84 the file user ID is the effective user ID of the creating process.
85 The user ID of a file can be changed using
89 \fIstat.st_gid\fP; \fIstatx.stx_gid\fP
91 The inode records the ID of the group owner of the file.
92 For newly created files,
93 the file group ID is either the group ID of the parent directory or
94 the effective group ID of the creating process,
95 depending on whether or not the set-group-ID bit
96 is set on the parent directory (see below).
97 The group ID of a file can be changed using
100 Device represented by this inode
101 \fIstat.st_rdev\fP; \fIstatx.stx_rdev_minor\fP and \fIstatx.stx_rdev_major\fP
103 If this file (inode) represents a device,
104 then the inode records the major and minor ID of that device.
107 \fIstat.st_size\fP; \fIstatx.stx_size\fP
109 This field gives the size of the file (if it is a regular
110 file or a symbolic link) in bytes.
111 The size of a symbolic link is the length of the pathname
112 it contains, without a terminating null byte.
114 Preferred block size for I/O
115 \fIstat.st_blksize\fP; \fIstatx.stx_blksize\fP
117 This field gives the "preferred" blocksize for efficient filesystem I/O.
118 (Writing to a file in smaller chunks may cause
119 an inefficient read-modify-rewrite.)
121 Number of blocks allocated to the file
122 \fIstat.st_blocks\fP; \fIstatx.stx_size\fP
124 This field indicates the number of blocks allocated to the file,
126 (This may be smaller than
128 when the file has holes.)
130 The POSIX.1 standard notes
131 .\" Rationale for sys/stat.h in POSIX.1-2008
132 that the unit for the
136 structure is not defined by the standard.
137 On many implementations it is 512 bytes;
138 on a few systems, a different unit is used, such as 1024.
139 Furthermore, the unit may differ on a per-filesystem basis.
141 Last access timestamp (atime)
142 \fIstat.st_atime\fP; \fIstatx.stx_atime\fP
144 This is the file's last access timestamp.
145 It is changed by file accesses, for example, by
152 (of more than zero bytes).
153 Other interfaces, such as
155 may or may not update the atime timestamp
157 Some filesystem types allow mounting in such a way that file
158 and/or directory accesses do not cause an update of the atime timestamp.
166 and related information in
168 In addition, the atime timestamp
169 is not updated if a file is opened with the
174 File creation (birth) timestamp (btime)
175 (not returned in the \fIstat\fP structure); \fIstatx.stx_btime\fP
177 The file's creation timestamp.
178 This is set on file creation and not changed subsequently.
180 The btime timestamp was not historically present on UNIX systems
181 and is not currently supported by most Linux filesystems.
182 .\" FIXME Is it supported on ext4 and XFS?
184 Last modification timestamp (mtime)
185 \fIstat.st_atime\fP; \fIstatx.stx_mtime\fP
187 This is the file's last modification timestamp.
188 It is changed by file modifications, for example, by
194 (of more than zero bytes).
195 Moreover, the mtime timestamp
196 of a directory is changed by the creation or deletion of files
198 The mtime timestamp is
200 changed for changes in owner, group, hard link count, or mode.
202 Last status change timestamp (ctime)
203 \fIstat.st_ctime\fP; \fIstatx.stx_ctime\fP
205 This is the file's last status change timestamp.
206 It is changed by writing or by setting inode information
207 (i.e., owner, group, link count, mode, etc.).
209 Nanosecond timestamps are supported on XFS, JFS, Btrfs, and
210 ext4 (since Linux 2.6.23).
211 .\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80
212 Nanosecond timestamps are not supported in ext2, ext3, and Reiserfs.
213 On filesystems that do not support subsecond timestamps,
214 the nanosecond fields in the
218 structures are returned with the value 0.
220 .SS The file type and mode
227 field) contains the file type and mode.
231 bits corresponding to the mask
235 the 12 bits corresponding to the mask 07777 as the
237 and the least significant 9 bits (0777) as the
238 .IR "file permission bits" .
240 The following mask values are defined for the file type:
244 S_IFMT 0170000 bit mask for the file type bit field
246 S_IFSOCK 0140000 socket
247 S_IFLNK 0120000 symbolic link
248 S_IFREG 0100000 regular file
249 S_IFBLK 0060000 block device
250 S_IFDIR 0040000 directory
251 S_IFCHR 0020000 character device
256 Thus, to test for a regular file (for example), one could write:
261 if ((sb.st_mode & S_IFMT) == S_IFREG) {
262 /* Handle regular file */
267 Because tests of the above form are common, additional
268 macros are defined by POSIX to allow the test of the file type in
270 to be written more concisely:
274 is it a regular file?
289 symbolic link? (Not in POSIX.1-1996.)
292 socket? (Not in POSIX.1-1996.)
295 The preceding code snippet could thus be rewritten as:
300 if (S_ISREG(sb.st_mode)) {
301 /* Handle regular file */
306 The definitions of most of the above file type test macros
307 are provided if any of the following feature test macros is defined:
309 (in glibc 2.19 and earlier),
311 (in glibc 2.19 and earlier),
314 (in glibc 2.20 and later).
315 In addition, definitions of all of the above macros except
325 can also be exposed either by defining
327 with a value of 500 or greater or (since glibc 2.24) by defining both
330 .BR _XOPEN_SOURCE_EXTENDED .
334 is exposed if any of the following feature test macros is defined:
336 (in glibc 2.19 and earlier),
338 (in glibc 2.20 and later),
340 with a value of 500 or greater,
342 with a value of 200112L or greater, or (since glibc 2.24) by defining both
345 .BR _XOPEN_SOURCE_EXTENDED .
347 The following mask values are defined for
348 the file mode component of the
354 S_ISUID 04000 set-user-ID bit
355 S_ISGID 02000 set-group-ID bit (see below)
356 S_ISVTX 01000 sticky bit (see below)
358 S_IRWXU 00700 owner has read, write, and execute permission
359 S_IRUSR 00400 owner has read permission
360 S_IWUSR 00200 owner has write permission
361 S_IXUSR 00100 owner has execute permission
363 S_IRWXG 00070 group has read, write, and execute permission
364 S_IRGRP 00040 group has read permission
365 S_IWGRP 00020 group has write permission
366 S_IXGRP 00010 group has execute permission
369 others (not in group) have read, write, and execute permission
371 S_IROTH 00004 others have read permission
372 S_IWOTH 00002 others have write permission
373 S_IXOTH 00001 others have execute permission
379 has several special uses.
380 For a directory, it indicates that BSD semantics is to be used
381 for that directory: files created there inherit their group ID from
382 the directory, not from the effective group ID of the creating process,
383 and directories created there will also get the
386 For a file that does not have the group execution bit
389 the set-group-ID bit indicates mandatory file/record locking.
393 on a directory means that a file
394 in that directory can be renamed or deleted only by the owner
395 of the file, by the owner of the directory, and by a privileged
398 If you need to obtain the definition of the
406 with the value 500 or greater (before including
410 POSIX.1-1990 did not describe the
420 constants, but instead specified the use of
426 constants are present in POSIX.1-2001 and later.
433 POSIX.1-1996, but both are present in POSIX.1-2001;
434 the former is from SVID 4, the latter from SUSv2.
436 UNIX\ V7 (and later systems) had
441 prescribes the synonyms
446 For pseudofiles that are autogenerated by the kernel, the file size
447 (\fIstat.st_size\fP; \fIstatx.stx_size\fP)
448 reported by the kernel is not accurate.
449 For example, the value 0 is returned for many files under the
452 while various files under
454 report a size of 4096 bytes, even though the file content is smaller.
455 For such files, one should simply try to read as many bytes as possible
456 (and append \(aq\e0\(aq to the returned buffer
457 if it is to be interpreted as a string).