man7/inode.7

   1 '\" t
   2 .\" Copyright (c) 2017 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   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.
   8 .\"
   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.
  13 .\"
  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
  20 .\" professionally.
  21 .\"
  22 .\" Formatted or processed versions of this manual, if unaccompanied by
  23 .\" the source, must acknowledge the copyright and authors of this work.
  24 .\" %%%LICENSE_END
  25 .\"
  26 .TH INODE 7 2017-09-15 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 inode \- file inode information
  29 .SH DESCRIPTION
  30 Each file has an inode containing metadata about the file.
  31 An application can retrieve this metadata using
  32 .BR stat (2)
  33 (or related calls), which returns a
  34 .I stat
  35 structure, or
  36 .BR statx (2),
  37 which returns a
  38 .I statx
  39 structure.
  40 .PP
  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
  44 .BR stat (2)
  45 and
  46 .BR statx (2):
  47 .TP
  48 Device where inode resides
  49 \fIstat.st_dev\fP; \fIstatx.stx_dev_minor\fP and \fIstatx.stx_dev_major\fP
  50 .IP
  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).
  56 .TP
  57 Inode number
  58 \fIstat.st_ino\fP; \fIstatx.stx_ino\fP
  59 .IP
  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.
  65 .TP
  66 File type and mode
  67 \fIstat.st_mode\fP; \fIstatx.stx_mode\fP
  68 .IP
  69 See the discussion of file type and mode, below.
  70 .TP
  71 Link count
  72 \fIstat.st_nlink\fP; \fIstatx.stx_nlink\fP
  73 .IP
  74 This field contains the number of hard links to the file.
  75 Additional links to an existing file are created using
  76 .BR link (2).
  77 .TP
  78 User ID
  79 .I st_uid
  80 \fIstat.st_uid\fP; \fIstatx.stx_uid\fP
  81 .IP
  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
  86 .BR chown (2).
  87 .TP
  88 Group ID
  89 \fIstat.st_gid\fP; \fIstatx.stx_gid\fP
  90 .IP
  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
  98 .BR chown (2).
  99 .TP
 100 Device represented by this inode
 101 \fIstat.st_rdev\fP; \fIstatx.stx_rdev_minor\fP and \fIstatx.stx_rdev_major\fP
 102 .IP
 103 If this file (inode) represents a device,
 104 then the inode records the major and minor ID of that device.
 105 .TP
 106 File size
 107 \fIstat.st_size\fP; \fIstatx.stx_size\fP
 108 .IP
 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.
 113 .TP
 114 Preferred block size for I/O
 115 \fIstat.st_blksize\fP; \fIstatx.stx_blksize\fP
 116 .IP
 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.)
 120 .TP
 121 Number of blocks allocated to the file
 122 \fIstat.st_blocks\fP; \fIstatx.stx_size\fP
 123 .IP
 124 This field indicates the number of blocks allocated to the file,
 125 512-byte units,
 126 (This may be smaller than
 127 .IR st_size /512
 128 when the file has holes.)
 129 .IP
 130 The POSIX.1 standard notes
 131 .\" Rationale for sys/stat.h in POSIX.1-2008
 132 that the unit for the
 133 .I st_blocks
 134 member of the
 135 .I stat
 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.
 140 .TP
 141 Last access timestamp (atime)
 142 \fIstat.st_atime\fP; \fIstatx.stx_atime\fP
 143 .IP
 144 This is the file's last access timestamp.
 145 It is changed by file accesses, for example, by
 146 .BR execve (2),
 147 .BR mknod (2),
 148 .BR pipe (2),
 149 .BR utime (2),
 150 and
 151 .BR read (2)
 152 (of more than zero bytes).
 153 Other interfaces, such as
 154 .BR mmap (2),
 155 may or may not update the atime timestamp
 156 .IP
 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.
 159 (See
 160 .IR noatime ,
 161 .IR nodiratime ,
 162 and
 163 .I relatime
 164 in
 165 .BR mount (8),
 166 and related information in
 167 .BR mount (2).)
 168 In addition, the atime timestamp
 169 is not updated if a file is opened with the
 170 .BR O_NOATIME
 171 flag; see
 172 .BR open (2).
 173 .TP
 174 File creation (birth) timestamp (btime)
 175 (not returned in the \fIstat\fP structure); \fIstatx.stx_btime\fP
 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 \fIstat.st_mtime\fP; \fIstatx.stx_mtime\fP
 186 .IP
 187 This is the file's last modification timestamp.
 188 It is changed by file modifications, for example, by
 189 .BR mknod (2),
 190 .BR truncate (2),
 191 .BR utime (2),
 192 and
 193 .BR write (2)
 194 (of more than zero bytes).
 195 Moreover, the mtime timestamp
 196 of a directory is changed by the creation or deletion of files
 197 in that directory.
 198 The mtime timestamp is
 199 .I not
 200 changed for changes in owner, group, hard link count, or mode.
 201 .TP
 202 Last status change timestamp (ctime)
 203 \fIstat.st_ctime\fP; \fIstatx.stx_ctime\fP
 204 .IP
 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.).
 208 .PP
 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 In order to return timestamps with nanosecond precision,
 214 the timestamp fields in the
 215 .I stat
 216 and
 217 .I statx
 218 structures are defined as structures that include a nanosecond component.
 219 See
 220 .BR stat (2)
 221 and
 222 .BR statx (2)
 223 for details.
 224 On filesystems that do not support subsecond timestamps,
 225 the nanosecond fields in the
 226 .I stat
 227 and
 228 .I statx
 229 structures are returned with the value 0.
 230 .\"
 231 .SS The file type and mode
 232 The
 233 .I stat.st_mode
 234 field (for
 235 .BR statx (2),
 236 the
 237 .I statx.stx_mode
 238 field) contains the file type and mode.
 239 .PP
 240 POSIX refers to the
 241 .I stat.st_mode
 242 bits corresponding to the mask
 243 .B S_IFMT
 244 (see below) as the
 245 .IR "file type" ,
 246 the 12 bits corresponding to the mask 07777 as the
 247 .IR "file mode bits"
 248 and the least significant 9 bits (0777) as the
 249 .IR "file permission bits" .
 250 .PP
 251 The following mask values are defined for the file type:
 252 .in +4n
 253 .TS
 254 lB l l.
 255 S_IFMT  0170000 bit mask for the file type bit field
 256
 257 S_IFSOCK        0140000 socket
 258 S_IFLNK 0120000 symbolic link
 259 S_IFREG 0100000 regular file
 260 S_IFBLK 0060000 block device
 261 S_IFDIR 0040000 directory
 262 S_IFCHR 0020000 character device
 263 S_IFIFO 0010000 FIFO
 264 .TE
 265 .in
 266 .PP
 267 Thus, to test for a regular file (for example), one could write:
 268 .PP
 269 .in +4n
 270 .EX
 271 stat(pathname, &sb);
 272 if ((sb.st_mode & S_IFMT) == S_IFREG) {
 273     /* Handle regular file */
 274 }
 275 .EE
 276 .in
 277 .PP
 278 Because tests of the above form are common, additional
 279 macros are defined by POSIX to allow the test of the file type in
 280 .I st_mode
 281 to be written more concisely:
 282 .RS 4
 283 .TP 1.2i
 284 .BR S_ISREG (m)
 285 is it a regular file?
 286 .TP
 287 .BR S_ISDIR (m)
 288 directory?
 289 .TP
 290 .BR S_ISCHR (m)
 291 character device?
 292 .TP
 293 .BR S_ISBLK (m)
 294 block device?
 295 .TP
 296 .BR S_ISFIFO (m)
 297 FIFO (named pipe)?
 298 .TP
 299 .BR S_ISLNK (m)
 300 symbolic link?  (Not in POSIX.1-1996.)
 301 .TP
 302 .BR S_ISSOCK (m)
 303 socket?  (Not in POSIX.1-1996.)
 304 .RE
 305 .PP
 306 The preceding code snippet could thus be rewritten as:
 307 .PP
 308 .in +4n
 309 .EX
 310 stat(pathname, &sb);
 311 if (S_ISREG(sb.st_mode)) {
 312     /* Handle regular file */
 313 }
 314 .EE
 315 .in
 316 .PP
 317 The definitions of most of the above file type test macros
 318 are provided if any of the following feature test macros is defined:
 319 .BR _BSD_SOURCE
 320 (in glibc 2.19 and earlier),
 321 .BR _SVID_SOURCE
 322 (in glibc 2.19 and earlier),
 323 or
 324 .BR _DEFAULT_SOURCE
 325 (in glibc 2.20 and later).
 326 In addition, definitions of all of the above macros except
 327 .BR S_IFSOCK
 328 and
 329 .BR S_ISSOCK ()
 330 are provided if
 331 .BR _XOPEN_SOURCE
 332 is defined.
 333 .PP
 334 The definition of
 335 .BR S_IFSOCK
 336 can also be exposed either by defining
 337 .BR _XOPEN_SOURCE
 338 with a value of 500 or greater or (since glibc 2.24) by defining both
 339 .BR _XOPEN_SOURCE
 340 and
 341 .BR _XOPEN_SOURCE_EXTENDED .
 342 .PP
 343 The definition of
 344 .BR S_ISSOCK ()
 345 is exposed if any of the following feature test macros is defined:
 346 .BR _BSD_SOURCE
 347 (in glibc 2.19 and earlier),
 348 .BR _DEFAULT_SOURCE
 349 (in glibc 2.20 and later),
 350 .BR _XOPEN_SOURCE
 351 with a value of 500 or greater,
 352 .BR _POSIX_C_SOURCE
 353 with a value of 200112L or greater, or (since glibc 2.24) by defining both
 354 .BR _XOPEN_SOURCE
 355 and
 356 .BR _XOPEN_SOURCE_EXTENDED .
 357 .PP
 358 The following mask values are defined for
 359 the file mode component of the
 360 .I st_mode
 361 field:
 362 .in +4n
 363 .TS
 364 lB l l.
 365 S_ISUID   04000 set-user-ID bit
 366 S_ISGID   02000 set-group-ID bit (see below)
 367 S_ISVTX   01000 sticky bit (see below)
 368
 369 S_IRWXU   00700 owner has read, write, and execute permission
 370 S_IRUSR   00400 owner has read permission
 371 S_IWUSR   00200 owner has write permission
 372 S_IXUSR   00100 owner has execute permission
 373
 374 S_IRWXG   00070 group has read, write, and execute permission
 375 S_IRGRP   00040 group has read permission
 376 S_IWGRP   00020 group has write permission
 377 S_IXGRP   00010 group has execute permission
 378
 379 S_IRWXO   00007 T{
 380 others (not in group) have read, write, and execute permission
 381 T}
 382 S_IROTH   00004 others have read permission
 383 S_IWOTH   00002 others have write permission
 384 S_IXOTH   00001 others have execute permission
 385 .TE
 386 .in
 387 .PP
 388 The set-group-ID bit
 389 .RB ( S_ISGID )
 390 has several special uses.
 391 For a directory, it indicates that BSD semantics is to be used
 392 for that directory: files created there inherit their group ID from
 393 the directory, not from the effective group ID of the creating process,
 394 and directories created there will also get the
 395 .B S_ISGID
 396 bit set.
 397 For a file that does not have the group execution bit
 398 .RB ( S_IXGRP )
 399 set,
 400 the set-group-ID bit indicates mandatory file/record locking.
 401 .PP
 402 The sticky bit
 403 .RB ( S_ISVTX )
 404 on a directory means that a file
 405 in that directory can be renamed or deleted only by the owner
 406 of the file, by the owner of the directory, and by a privileged
 407 process.
 408 .SH CONFORMING TO
 409 If you need to obtain the definition of the
 410 .IR blkcnt_t
 411 or
 412 .IR blksize_t
 413 types from
 414 .IR <sys/stat.h> ,
 415 then define
 416 .BR _XOPEN_SOURCE
 417 with the value 500 or greater (before including
 418 .I any
 419 header files).
 420 .PP
 421 POSIX.1-1990 did not describe the
 422 .BR S_IFMT ,
 423 .BR S_IFSOCK ,
 424 .BR S_IFLNK ,
 425 .BR S_IFREG ,
 426 .BR S_IFBLK ,
 427 .BR S_IFDIR ,
 428 .BR S_IFCHR ,
 429 .BR S_IFIFO ,
 430 .B S_ISVTX
 431 constants, but instead specified the use of
 432 the macros
 433 .BR S_ISDIR (),
 434 and so on.
 435 The
 436 .BR S_IF*
 437 constants are present in POSIX.1-2001 and later.
 438 .PP
 439 The
 440 .BR S_ISLNK ()
 441 and
 442 .BR S_ISSOCK ()
 443 macros were not in
 444 POSIX.1-1996, but both are present in POSIX.1-2001;
 445 the former is from SVID 4, the latter from SUSv2.
 446 .PP
 447 UNIX\ V7 (and later systems) had
 448 .BR S_IREAD ,
 449 .BR S_IWRITE ,
 450 .BR S_IEXEC ,
 451 where POSIX
 452 prescribes the synonyms
 453 .BR S_IRUSR ,
 454 .BR S_IWUSR ,
 455 .BR S_IXUSR .
 456 .SH NOTES
 457 For pseudofiles that are autogenerated by the kernel, the file size
 458 (\fIstat.st_size\fP; \fIstatx.stx_size\fP)
 459 reported by the kernel is not accurate.
 460 For example, the value 0 is returned for many files under the
 461 .I /proc
 462 directory,
 463 while various files under
 464 .IR /sys
 465 report a size of 4096 bytes, even though the file content is smaller.
 466 For such files, one should simply try to read as many bytes as possible
 467 (and append \(aq\e0\(aq to the returned buffer
 468 if it is to be interpreted as a string).
 469 .SH SEE ALSO
 470 .BR stat (1),
 471 .BR stat (2),
 472 .BR statx (2),
 473 .BR symlink (7)