| 1 |
'\" t |
| 2 |
.\" Copyright 2017, Michael Kerrisk <[email protected]> |
| 3 |
.\" Copyright, the authors of the Linux man-pages project |
| 4 |
.\" |
| 5 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 6 |
.\" |
| 7 |
.TH inode 7 2026-02-08 "Linux man-pages 6.18" |
| 8 |
.SH NAME |
| 9 |
inode \- file inode information |
| 10 |
.SH DESCRIPTION |
| 11 |
Each file has an inode containing metadata about the file. |
| 12 |
An application can retrieve this metadata using |
| 13 |
.BR stat (2) |
| 14 |
(or related calls), which returns a |
| 15 |
.I stat |
| 16 |
structure, or |
| 17 |
.BR statx (2), |
| 18 |
which returns a |
| 19 |
.I statx |
| 20 |
structure. |
| 21 |
.P |
| 22 |
The following is a list of the information typically found in, |
| 23 |
or associated with, the file inode, |
| 24 |
with the names of the corresponding structure fields returned by |
| 25 |
.BR stat (2) |
| 26 |
and |
| 27 |
.BR statx (2): |
| 28 |
.TP |
| 29 |
Device where inode resides |
| 30 |
.IR stat.st_dev ; |
| 31 |
.I statx.stx_dev_minor |
| 32 |
and |
| 33 |
.I statx.stx_dev_major |
| 34 |
.IP |
| 35 |
Each inode (as well as the associated file) resides in a filesystem |
| 36 |
that is hosted on a device. |
| 37 |
That device is identified by the combination of its major ID |
| 38 |
(which identifies the general class of device) |
| 39 |
and minor ID (which identifies a specific instance in the general class). |
| 40 |
.TP |
| 41 |
Inode number |
| 42 |
.IR stat.st_ino ; |
| 43 |
.I statx.stx_ino |
| 44 |
.IP |
| 45 |
Each file in a filesystem has a unique inode number. |
| 46 |
Inode numbers are guaranteed to be unique only within a filesystem |
| 47 |
(i.e., the same inode numbers may be used by different filesystems, |
| 48 |
which is the reason that hard links may not cross filesystem boundaries). |
| 49 |
This field contains the file's inode number. |
| 50 |
.TP |
| 51 |
File type and mode |
| 52 |
.IR stat.st_mode ; |
| 53 |
.I statx.stx_mode |
| 54 |
.IP |
| 55 |
See the discussion of file type and mode, below. |
| 56 |
.TP |
| 57 |
Link count |
| 58 |
.IR stat.st_nlink ; |
| 59 |
.I statx.stx_nlink |
| 60 |
.IP |
| 61 |
This field contains the number of hard links to the file. |
| 62 |
Additional links to an existing file are created using |
| 63 |
.BR link (2). |
| 64 |
.TP |
| 65 |
User ID |
| 66 |
.IR stat.st_uid ; |
| 67 |
.I statx.stx_uid |
| 68 |
.IP |
| 69 |
This field records the user ID of the owner of the file. |
| 70 |
For newly created files, |
| 71 |
the file user ID is the effective user ID of the creating process. |
| 72 |
The user ID of a file can be changed using |
| 73 |
.BR chown (2). |
| 74 |
.TP |
| 75 |
Group ID |
| 76 |
.IR stat.st_gid ; |
| 77 |
.I statx.stx_gid |
| 78 |
.IP |
| 79 |
The inode records the ID of the group owner of the file. |
| 80 |
For newly created files, |
| 81 |
the file group ID is either the group ID of the parent directory or |
| 82 |
the effective group ID of the creating process, |
| 83 |
depending on whether or not the set-group-ID bit |
| 84 |
is set on the parent directory (see below). |
| 85 |
The group ID of a file can be changed using |
| 86 |
.BR chown (2). |
| 87 |
.TP |
| 88 |
Device represented by this inode |
| 89 |
.IR stat.st_rdev ; |
| 90 |
.I statx.stx_rdev_minor |
| 91 |
and |
| 92 |
.I statx.stx_rdev_major |
| 93 |
.IP |
| 94 |
If this file (inode) represents a device, |
| 95 |
then the inode records the major and minor ID of that device. |
| 96 |
.TP |
| 97 |
File size |
| 98 |
.IR stat.st_size ; |
| 99 |
.I statx.stx_size |
| 100 |
.IP |
| 101 |
This field gives the size of the file (if it is a regular |
| 102 |
file or a symbolic link) in bytes. |
| 103 |
The size of a symbolic link is the length of the pathname |
| 104 |
it contains, without a terminating null byte. |
| 105 |
.TP |
| 106 |
Preferred block size for I/O |
| 107 |
.IR stat.st_blksize ; |
| 108 |
.I statx.stx_blksize |
| 109 |
.IP |
| 110 |
This field gives the "preferred" blocksize for efficient filesystem I/O. |
| 111 |
(Writing to a file in smaller chunks may cause |
| 112 |
an inefficient read-modify-rewrite.) |
| 113 |
.TP |
| 114 |
Number of blocks allocated to the file |
| 115 |
.IR stat.st_blocks ; |
| 116 |
.I statx.stx_blocks |
| 117 |
.IP |
| 118 |
This field indicates the number of blocks allocated to the file, |
| 119 |
512-byte units, |
| 120 |
(This may be smaller than |
| 121 |
.IR st_size /512 |
| 122 |
when the file has holes.) |
| 123 |
.IP |
| 124 |
The POSIX.1 standard notes |
| 125 |
.\" Rationale for sys/stat.h in POSIX.1-2008 |
| 126 |
that the unit for the |
| 127 |
.I st_blocks |
| 128 |
member of the |
| 129 |
.I stat |
| 130 |
structure is not defined by the standard. |
| 131 |
On many implementations it is 512 bytes; |
| 132 |
on a few systems, a different unit is used, such as 1024. |
| 133 |
Furthermore, the unit may differ on a per-filesystem basis. |
| 134 |
.TP |
| 135 |
Last access timestamp (atime) |
| 136 |
.IR stat.st_atime ; |
| 137 |
.I statx.stx_atime |
| 138 |
.IP |
| 139 |
This is the file's last access timestamp. |
| 140 |
It is changed by file accesses, for example, by |
| 141 |
.BR execve (2), |
| 142 |
.BR mknod (2), |
| 143 |
.BR pipe (2), |
| 144 |
.BR utime (2), |
| 145 |
and |
| 146 |
.BR read (2) |
| 147 |
(of more than zero bytes). |
| 148 |
Other interfaces, such as |
| 149 |
.BR mmap (2), |
| 150 |
may or may not update the atime timestamp |
| 151 |
.IP |
| 152 |
Some filesystem types allow mounting in such a way that file |
| 153 |
and/or directory accesses do not cause an update of the atime timestamp. |
| 154 |
(See |
| 155 |
.IR noatime , |
| 156 |
.IR nodiratime , |
| 157 |
and |
| 158 |
.I relatime |
| 159 |
in |
| 160 |
.BR mount (8), |
| 161 |
and related information in |
| 162 |
.BR mount (2).) |
| 163 |
In addition, |
| 164 |
the atime timestamp |
| 165 |
is not updated if a file is opened with the |
| 166 |
.B O_NOATIME |
| 167 |
flag; |
| 168 |
see |
| 169 |
.BR open (2). |
| 170 |
.TP |
| 171 |
File creation (birth) timestamp (btime) |
| 172 |
(not returned in the |
| 173 |
.I stat |
| 174 |
structure); |
| 175 |
.I statx.stx_btime |
| 176 |
.IP |
| 177 |
The file's creation timestamp. |
| 178 |
This is set on file creation and not changed subsequently. |
| 179 |
.IP |
| 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? |
| 183 |
.TP |
| 184 |
Last modification timestamp (mtime) |
| 185 |
.IR stat.st_mtime ; |
| 186 |
.I statx.stx_mtime |
| 187 |
.IP |
| 188 |
This is the file's last modification timestamp. |
| 189 |
It is changed by file modifications, for example, by |
| 190 |
.BR mknod (2), |
| 191 |
.BR truncate (2), |
| 192 |
.BR utime (2), |
| 193 |
and |
| 194 |
.BR write (2) |
| 195 |
(of more than zero bytes). |
| 196 |
Moreover, the mtime timestamp |
| 197 |
of a directory is changed by the creation or deletion of files |
| 198 |
in that directory. |
| 199 |
The mtime timestamp is |
| 200 |
.I not |
| 201 |
changed for changes in owner, group, hard link count, or mode. |
| 202 |
.TP |
| 203 |
Last status change timestamp (ctime) |
| 204 |
.IR stat.st_ctime ; |
| 205 |
.I statx.stx_ctime |
| 206 |
.IP |
| 207 |
This is the file's last status change timestamp. |
| 208 |
It is changed by writing or by setting inode information |
| 209 |
(i.e., owner, group, link count, mode, etc.). |
| 210 |
.P |
| 211 |
The timestamp fields report time measured with a zero point at the |
| 212 |
.IR Epoch , |
| 213 |
1970-01-01 00:00:00 +0000, UTC (see |
| 214 |
.BR time (7)). |
| 215 |
.P |
| 216 |
Nanosecond timestamps are supported on XFS, JFS, Btrfs, and |
| 217 |
ext4 (since Linux 2.6.23). |
| 218 |
.\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80 |
| 219 |
Nanosecond timestamps are not supported in ext2, ext3, and Reiserfs. |
| 220 |
In order to return timestamps with nanosecond precision, |
| 221 |
the timestamp fields in the |
| 222 |
.I stat |
| 223 |
and |
| 224 |
.I statx |
| 225 |
structures are defined as structures that include a nanosecond component. |
| 226 |
See |
| 227 |
.BR stat (2) |
| 228 |
and |
| 229 |
.BR statx (2) |
| 230 |
for details. |
| 231 |
On filesystems that do not support subsecond timestamps, |
| 232 |
the nanosecond fields in the |
| 233 |
.I stat |
| 234 |
and |
| 235 |
.I statx |
| 236 |
structures are returned with the value 0. |
| 237 |
.\" |
| 238 |
.SS The file type and mode |
| 239 |
The |
| 240 |
.I stat.st_mode |
| 241 |
field (for |
| 242 |
.BR statx (2), |
| 243 |
the |
| 244 |
.I statx.stx_mode |
| 245 |
field) contains the file type and mode. |
| 246 |
.P |
| 247 |
POSIX refers to the |
| 248 |
.I stat.st_mode |
| 249 |
bits corresponding to the mask |
| 250 |
.B S_IFMT |
| 251 |
(see below) as the |
| 252 |
.IR "file type" , |
| 253 |
the 12 bits corresponding to the mask 07777 as the |
| 254 |
.I file mode bits |
| 255 |
and the least significant 9 bits (0777) as the |
| 256 |
.IR "file permission bits" . |
| 257 |
.P |
| 258 |
The following mask values are defined for the file type: |
| 259 |
.in +4n |
| 260 |
.TS |
| 261 |
lB l l. |
| 262 |
S_IFMT 0170000 bit mask for the file type bit field |
| 263 |
\& |
| 264 |
S_IFSOCK 0140000 socket |
| 265 |
S_IFLNK 0120000 symbolic link |
| 266 |
S_IFREG 0100000 regular file |
| 267 |
S_IFBLK 0060000 block device |
| 268 |
S_IFDIR 0040000 directory |
| 269 |
S_IFCHR 0020000 character device |
| 270 |
S_IFIFO 0010000 FIFO |
| 271 |
.TE |
| 272 |
.in |
| 273 |
.P |
| 274 |
Thus, to test for a regular file (for example), one could write: |
| 275 |
.P |
| 276 |
.in +4n |
| 277 |
.EX |
| 278 |
stat(pathname, &sb); |
| 279 |
if ((sb.st_mode & S_IFMT) == S_IFREG) { |
| 280 |
/* Handle regular file */ |
| 281 |
} |
| 282 |
.EE |
| 283 |
.in |
| 284 |
.P |
| 285 |
Because tests of the above form are common, additional |
| 286 |
macros are defined by POSIX to allow the test of the file type in |
| 287 |
.I st_mode |
| 288 |
to be written more concisely: |
| 289 |
.RS 4 |
| 290 |
.TP 1.2i |
| 291 |
.BR S_ISREG (m) |
| 292 |
is it a regular file? |
| 293 |
.TP |
| 294 |
.BR S_ISDIR (m) |
| 295 |
directory? |
| 296 |
.TP |
| 297 |
.BR S_ISCHR (m) |
| 298 |
character device? |
| 299 |
.TP |
| 300 |
.BR S_ISBLK (m) |
| 301 |
block device? |
| 302 |
.TP |
| 303 |
.BR S_ISFIFO (m) |
| 304 |
FIFO (named pipe)? |
| 305 |
.TP |
| 306 |
.BR S_ISLNK (m) |
| 307 |
symbolic link? (Not in POSIX.1-1996.) |
| 308 |
.TP |
| 309 |
.BR S_ISSOCK (m) |
| 310 |
socket? (Not in POSIX.1-1996.) |
| 311 |
.RE |
| 312 |
.P |
| 313 |
The preceding code snippet could thus be rewritten as: |
| 314 |
.P |
| 315 |
.in +4n |
| 316 |
.EX |
| 317 |
stat(pathname, &sb); |
| 318 |
if (S_ISREG(sb.st_mode)) { |
| 319 |
/* Handle regular file */ |
| 320 |
} |
| 321 |
.EE |
| 322 |
.in |
| 323 |
.P |
| 324 |
The definitions of most of the above file type test macros |
| 325 |
are provided if any of the following feature test macros is defined: |
| 326 |
.B _BSD_SOURCE |
| 327 |
(in glibc 2.19 and earlier), |
| 328 |
.B _SVID_SOURCE |
| 329 |
(in glibc 2.19 and earlier), |
| 330 |
or |
| 331 |
.B _DEFAULT_SOURCE |
| 332 |
(in glibc 2.20 and later). |
| 333 |
In addition, definitions of all of the above macros except |
| 334 |
.B S_IFSOCK |
| 335 |
and |
| 336 |
.BR S_ISSOCK () |
| 337 |
are provided if |
| 338 |
.B _XOPEN_SOURCE |
| 339 |
is defined. |
| 340 |
.P |
| 341 |
The definition of |
| 342 |
.B S_IFSOCK |
| 343 |
can also be exposed either by defining |
| 344 |
.B _XOPEN_SOURCE |
| 345 |
with a value of 500 or greater or (since glibc 2.24) by defining both |
| 346 |
.B _XOPEN_SOURCE |
| 347 |
and |
| 348 |
.BR _XOPEN_SOURCE_EXTENDED . |
| 349 |
.P |
| 350 |
The definition of |
| 351 |
.BR S_ISSOCK () |
| 352 |
is exposed if any of the following feature test macros is defined: |
| 353 |
.B _BSD_SOURCE |
| 354 |
(in glibc 2.19 and earlier), |
| 355 |
.B _DEFAULT_SOURCE |
| 356 |
(in glibc 2.20 and later), |
| 357 |
.B _XOPEN_SOURCE |
| 358 |
with a value of 500 or greater, |
| 359 |
.B _POSIX_C_SOURCE |
| 360 |
with a value of 200112L or greater, or (since glibc 2.24) by defining both |
| 361 |
.B _XOPEN_SOURCE |
| 362 |
and |
| 363 |
.BR _XOPEN_SOURCE_EXTENDED . |
| 364 |
.P |
| 365 |
The following mask values are defined for |
| 366 |
the file mode component of the |
| 367 |
.I st_mode |
| 368 |
field: |
| 369 |
.in +4n |
| 370 |
.TS |
| 371 |
lB l lx. |
| 372 |
S_ISUID 04000 T{ |
| 373 |
set-user-ID bit (see |
| 374 |
.BR execve (2)) |
| 375 |
T} |
| 376 |
S_ISGID 02000 T{ |
| 377 |
set-group-ID bit (see below) |
| 378 |
T} |
| 379 |
S_ISVTX 01000 T{ |
| 380 |
sticky bit (see below) |
| 381 |
T} |
| 382 |
\& |
| 383 |
S_IRWXU 00700 T{ |
| 384 |
owner has read, write, and execute permission |
| 385 |
T} |
| 386 |
S_IRUSR 00400 T{ |
| 387 |
owner has read permission |
| 388 |
T} |
| 389 |
S_IWUSR 00200 T{ |
| 390 |
owner has write permission |
| 391 |
T} |
| 392 |
S_IXUSR 00100 T{ |
| 393 |
owner has execute permission |
| 394 |
T} |
| 395 |
\& |
| 396 |
S_IRWXG 00070 T{ |
| 397 |
group has read, write, and execute permission |
| 398 |
T} |
| 399 |
S_IRGRP 00040 T{ |
| 400 |
group has read permission |
| 401 |
T} |
| 402 |
S_IWGRP 00020 T{ |
| 403 |
group has write permission |
| 404 |
T} |
| 405 |
S_IXGRP 00010 T{ |
| 406 |
group has execute permission |
| 407 |
T} |
| 408 |
\& |
| 409 |
S_IRWXO 00007 T{ |
| 410 |
others (not in group) have read, write, and execute permission |
| 411 |
T} |
| 412 |
S_IROTH 00004 T{ |
| 413 |
others have read permission |
| 414 |
T} |
| 415 |
S_IWOTH 00002 T{ |
| 416 |
others have write permission |
| 417 |
T} |
| 418 |
S_IXOTH 00001 T{ |
| 419 |
others have execute permission |
| 420 |
T} |
| 421 |
.TE |
| 422 |
.in |
| 423 |
.P |
| 424 |
The set-group-ID bit |
| 425 |
.RB ( S_ISGID ) |
| 426 |
has several special uses. |
| 427 |
For a directory, it indicates that BSD semantics are to be used |
| 428 |
for that directory: files created there inherit their group ID from |
| 429 |
the directory, not from the effective group ID of the creating process, |
| 430 |
and directories created there will also get the |
| 431 |
.B S_ISGID |
| 432 |
bit set. |
| 433 |
For an executable file, the set-group-ID bit causes the effective group ID |
| 434 |
of a process that executes the file to change as described in |
| 435 |
.BR execve (2). |
| 436 |
For a file that does not have the group execution bit |
| 437 |
.RB ( S_IXGRP ) |
| 438 |
set, |
| 439 |
the set-group-ID bit indicates mandatory file/record locking. |
| 440 |
.P |
| 441 |
The sticky bit |
| 442 |
.RB ( S_ISVTX ) |
| 443 |
on a directory means that a file |
| 444 |
in that directory can be renamed or deleted only by the owner |
| 445 |
of the file, by the owner of the directory, and by a privileged |
| 446 |
process. |
| 447 |
.SH STANDARDS |
| 448 |
POSIX.1-2008. |
| 449 |
.SH HISTORY |
| 450 |
POSIX.1-2001. |
| 451 |
.P |
| 452 |
POSIX.1-1990 did not describe the |
| 453 |
.BR S_IFMT , |
| 454 |
.BR S_IFSOCK , |
| 455 |
.BR S_IFLNK , |
| 456 |
.BR S_IFREG , |
| 457 |
.BR S_IFBLK , |
| 458 |
.BR S_IFDIR , |
| 459 |
.BR S_IFCHR , |
| 460 |
.BR S_IFIFO , |
| 461 |
and |
| 462 |
.B S_ISVTX |
| 463 |
constants, but instead specified the use of |
| 464 |
the macros |
| 465 |
.BR S_ISDIR () |
| 466 |
and so on. |
| 467 |
.P |
| 468 |
The |
| 469 |
.BR S_ISLNK () |
| 470 |
and |
| 471 |
.BR S_ISSOCK () |
| 472 |
macros were not in |
| 473 |
POSIX.1-1996; |
| 474 |
the former is from SVID 4, the latter from SUSv2. |
| 475 |
.P |
| 476 |
UNIX\ V7 (and later systems) had |
| 477 |
.BR S_IREAD , |
| 478 |
.BR S_IWRITE , |
| 479 |
.BR S_IEXEC , |
| 480 |
and |
| 481 |
where POSIX |
| 482 |
prescribes the synonyms |
| 483 |
.BR S_IRUSR , |
| 484 |
.BR S_IWUSR , |
| 485 |
and |
| 486 |
.BR S_IXUSR . |
| 487 |
.SH NOTES |
| 488 |
For pseudofiles that are autogenerated by the kernel, the file size |
| 489 |
.RI ( stat.st_size ; |
| 490 |
.IR statx.stx_size ) |
| 491 |
reported by the kernel is not accurate. |
| 492 |
For example, the value 0 is returned for many files under the |
| 493 |
.I /proc |
| 494 |
directory, |
| 495 |
while various files under |
| 496 |
.I /sys |
| 497 |
report a size of 4096 bytes, even though the file content is smaller. |
| 498 |
For such files, one should simply try to read as many bytes as possible |
| 499 |
(and append \[aq]\[rs]0\[aq] to the returned buffer |
| 500 |
if it is to be interpreted as a string). |
| 501 |
.SH SEE ALSO |
| 502 |
.BR stat (1), |
| 503 |
.BR stat (2), |
| 504 |
.BR statx (2), |
| 505 |
.BR symlink (7) |