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_mtime; 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 The timestamp fields report time measured with a zero point at the
141 Epoch, 1970-01-01 00:00:00 +0000, UTC (see time(7)).
142 Nanosecond timestamps are supported on XFS, JFS, Btrfs, and ext4 (since
144 Linux 2.6.23). Nanosecond timestamps are not supported in ext2, ext3,
145 and Reiserfs. In order to return timestamps with nanosecond precision,
146 the timestamp fields in the stat and statx structures are defined as
147 structures that include a nanosecond component. See stat(2) and
148 statx(2) for details. On filesystems that do not support subsecond
149 timestamps, the nanosecond fields in the stat and statx structures are
150 returned with the value 0.
151 The file type and mode
153 The stat.st_mode field (for statx(2), the statx.stx_mode field) con‐
154 tains the file type and mode.
155 POSIX refers to the stat.st_mode bits corresponding to the mask S_IFMT
157 (see below) as the file type, the 12 bits corresponding to the mask
158 07777 as the file mode bits and the least significant 9 bits (0777) as
159 the file permission bits.
160 The following mask values are defined for the file type:
162 S_IFMT 0170000 bit mask for the file type bit field
164 S_IFSOCK 0140000 socket
166 S_IFLNK 0120000 symbolic link
167 S_IFREG 0100000 regular file
168 S_IFBLK 0060000 block device
169 S_IFDIR 0040000 directory
170 S_IFCHR 0020000 character device
171 S_IFIFO 0010000 FIFO
172 Thus, to test for a regular file (for example), one could write:
174 stat(pathname, &sb);
176 if ((sb.st_mode & S_IFMT) == S_IFREG) {
177 /* Handle regular file */
178 }
179 Because tests of the above form are common, additional macros are de‐
181 fined by POSIX to allow the test of the file type in st_mode to be
182 written more concisely:
183 S_ISREG(m) is it a regular file?
185 S_ISDIR(m) directory?
187 S_ISCHR(m) character device?
189 S_ISBLK(m) block device?
191 S_ISFIFO(m) FIFO (named pipe)?
193 S_ISLNK(m) symbolic link? (Not in POSIX.1-1996.)
195 S_ISSOCK(m) socket? (Not in POSIX.1-1996.)
197 The preceding code snippet could thus be rewritten as:
199 stat(pathname, &sb);
201 if (S_ISREG(sb.st_mode)) {
202 /* Handle regular file */
203 }
204 The definitions of most of the above file type test macros are provided
206 if any of the following feature test macros is defined: _BSD_SOURCE (in
207 glibc 2.19 and earlier), _SVID_SOURCE (in glibc 2.19 and earlier), or
208 _DEFAULT_SOURCE (in glibc 2.20 and later). In addition, definitions of
209 all of the above macros except S_IFSOCK and S_ISSOCK() are provided if
210 _XOPEN_SOURCE is defined.
211 The definition of S_IFSOCK can also be exposed either by defining
213 _XOPEN_SOURCE with a value of 500 or greater or (since glibc 2.24) by
214 defining both _XOPEN_SOURCE and _XOPEN_SOURCE_EXTENDED.
215 The definition of S_ISSOCK() is exposed if any of the following feature
217 test macros is defined: _BSD_SOURCE (in glibc 2.19 and earlier), _DE‐
218 FAULT_SOURCE (in glibc 2.20 and later), _XOPEN_SOURCE with a value of
219 500 or greater, _POSIX_C_SOURCE with a value of 200112L or greater, or
220 (since glibc 2.24) by defining both _XOPEN_SOURCE and _XOPEN_SOURCE_EX‐
221 TENDED.
222 The following mask values are defined for the file mode component of
224 the st_mode field:
225 S_ISUID 04000 set-user-ID bit (see execve(2))
227 S_ISGID 02000 set-group-ID bit (see below)
228 S_ISVTX 01000 sticky bit (see below)
229 S_IRWXU 00700 owner has read, write, and execute permission
231 S_IRUSR 00400 owner has read permission
232 S_IWUSR 00200 owner has write permission
233 S_IXUSR 00100 owner has execute permission
234 S_IRWXG 00070 group has read, write, and execute permission
236 S_IRGRP 00040 group has read permission
237 S_IWGRP 00020 group has write permission
238 S_IXGRP 00010 group has execute permission
239 S_IRWXO 00007 others (not in group) have read, write, and
241 execute permission
242 S_IROTH 00004 others have read permission
243 S_IWOTH 00002 others have write permission
244 S_IXOTH 00001 others have execute permission
245 The set-group-ID bit (S_ISGID) has several special uses. For a direc‐
247 tory, it indicates that BSD semantics are to be used for that directo‐
248 ry: files created there inherit their group ID from the directory, not
249 from the effective group ID of the creating process, and directories
250 created there will also get the S_ISGID bit set. For an executable
251 file, the set-group-ID bit causes the effective group ID of a process
252 that executes the file to change as described in execve(2). For a file
253 that does not have the group execution bit (S_IXGRP) set, the set-
254 group-ID bit indicates mandatory file/record locking.
255 The sticky bit (S_ISVTX) on a directory means that a file in that di‐
257 rectory can be renamed or deleted only by the owner of the file, by the
258 owner of the directory, and by a privileged process.
259
261 If you need to obtain the definition of the blkcnt_t or blksize_t types
262 from <sys/stat.h>, then define _XOPEN_SOURCE with the value 500 or
263 greater (before including any header files).
264 POSIX.1-1990 did not describe the S_IFMT, S_IFSOCK, S_IFLNK, S_IFREG,
266 S_IFBLK, S_IFDIR, S_IFCHR, S_IFIFO, and S_ISVTX constants, but instead
267 specified the use of the macros S_ISDIR() and so on. The S_IF* con‐
268 stants are present in POSIX.1-2001 and later.
269 The S_ISLNK() and S_ISSOCK() macros were not in POSIX.1-1996, but both
271 are present in POSIX.1-2001; the former is from SVID 4, the latter from
272 SUSv2.
273 UNIX V7 (and later systems) had S_IREAD, S_IWRITE, S_IEXEC, and where
275 POSIX prescribes the synonyms S_IRUSR, S_IWUSR, and S_IXUSR.
276
278 For pseudofiles that are autogenerated by the kernel, the file size
279 (stat.st_size; statx.stx_size) reported by the kernel is not accurate.
280 For example, the value 0 is returned for many files under the /proc di‐
281 rectory, while various files under /sys report a size of 4096 bytes,
282 even though the file content is smaller. For such files, one should
283 simply try to read as many bytes as possible (and append '\0' to the
284 returned buffer if it is to be interpreted as a string).
285
287 stat(1), stat(2), statx(2), symlink(7)
288
290 This page is part of release 5.12 of the Linux man-pages project. A
291 description of the project, information about reporting bugs, and the
292 latest version of this page, can be found at
293 https://www.kernel.org/doc/man-pages/.
294Linux 2021-03-22 INODE(7)