INODE(7) Linux Programmer's Manual INODE(7)NAMEinode - file inode information
DESCRIPTION
Each file has an inode containing metadata about the file. An applica‐
tion can retrieve this metadata using stat(2) (or related calls), which
returns a stat structure, or statx(2), which returns a statx structure.
The following is a list of the information typically found in, or asso‐
ciated with, the file inode, with the names of the corresponding struc‐
ture fields returned by stat(2) and statx(2):
Device where inode resides
stat.st_dev; statx.stx_dev_minor and statx.stx_dev_major
Each inode (as well as the associated file) resides in a
filesystem that is hosted on a device. That device is identi‐
fied by the combination of its major ID (which identifies the
general class of device) and minor ID (which identifies a spe‐
cific instance in the general class).
Inode number
stat.st_ino; statx.stx_ino
Each file in a filesystem has a unique inode number. Inode num‐
bers are guaranteed to be unique only within a filesystem (i.e.,
the same inode numbers may be used by different filesystems,
which is the reason that hard links may not cross filesystem
boundaries). This field contains the file's inode number.
File type and mode
stat.st_mode; statx.stx_mode
See the discussion of file type and mode, below.
Link count
stat.st_nlink; statx.stx_nlink
This field contains the number of hard links to the file. Addi‐
tional links to an existing file are created using link(2).
User ID
st_uid stat.st_uid; statx.stx_uid
This field records the user ID of the owner of the file. For
newly created files, the file user ID is the effective user ID
of the creating process. The user ID of a file can be changed
using chown(2).
Group ID
stat.st_gid; statx.stx_gid
The inode records the ID of the group owner of the file. For
newly created files, the file group ID is either the group ID of
the parent directory or the effective group ID of the creating
process, depending on whether or not the set-group-ID bit is set
on the parent directory (see below). The group ID of a file can
be changed using chown(2).
Device represented by this inode
stat.st_rdev; statx.stx_rdev_minor and statx.stx_rdev_major
If this file (inode) represents a device, then the inode records
the major and minor ID of that device.
File size
stat.st_size; statx.stx_size
This field gives the size of the file (if it is a regular file
or a symbolic link) in bytes. The size of a symbolic link is
the length of the pathname it contains, without a terminating
null byte.
Preferred block size for I/O
stat.st_blksize; statx.stx_blksize
This field gives the "preferred" blocksize for efficient
filesystem I/O. (Writing to a file in smaller chunks may cause
an inefficient read-modify-rewrite.)
Number of blocks allocated to the file
stat.st_blocks; statx.stx_size
This field indicates the number of blocks allocated to the file,
512-byte units, (This may be smaller than st_size/512 when the
file has holes.)
The POSIX.1 standard notes that the unit for the st_blocks mem‐
ber of the stat structure is not defined by the standard. On
many implementations it is 512 bytes; on a few systems, a dif‐
ferent unit is used, such as 1024. Furthermore, the unit may
differ on a per-filesystem basis.
Last access timestamp (atime)
stat.st_atime; statx.stx_atime
This is the file's last access timestamp. It is changed by file
accesses, for example, by execve(2), mknod(2), pipe(2),
utime(2), and read(2) (of more than zero bytes). Other inter‐
faces, such as mmap(2), may or may not update the atime time‐
stamp
Some filesystem types allow mounting in such a way that file
and/or directory accesses do not cause an update of the atime
timestamp. (See noatime, nodiratime, and relatime in mount(8),
and related information in mount(2).) In addition, the atime
timestamp is not updated if a file is opened with the O_NOATIME
flag; see open(2).
File creation (birth) timestamp (btime)
(not returned in the stat structure); statx.stx_btime
The file's creation timestamp. This is set on file creation and
not changed subsequently.
The btime timestamp was not historically present on UNIX systems
and is not currently supported by most Linux filesystems.
Last modification timestamp (mtime)
stat.st_atime; statx.stx_mtime
This is the file's last modification timestamp. It is changed
by file modifications, for example, by mknod(2), truncate(2),
utime(2), and write(2) (of more than zero bytes). Moreover, the
mtime timestamp of a directory is changed by the creation or
deletion of files in that directory. The mtime timestamp is not
changed for changes in owner, group, hard link count, or mode.
Last status change timestamp (ctime)
stat.st_ctime; statx.stx_ctime
This is the file's last status change timestamp. It is changed
by writing or by setting inode information (i.e., owner, group,
link count, mode, etc.).
Nanosecond timestamps are supported on XFS, JFS, Btrfs, and ext4 (since
Linux 2.6.23). Nanosecond timestamps are not supported in ext2, ext3,
and Reiserfs. On filesystems that do not support subsecond timestamps,
the nanosecond fields in the stat and statx structures are returned
with the value 0.
The file type and mode
The stat.st_mode field (for statx(2), the statx.stx_mode field) con‐
tains the file type and mode.
POSIX refers to the stat.st_mode bits corresponding to the mask S_IFMT
(see below) as the file type, the 12 bits corresponding to the mask
07777 as the file mode bits and the least significant 9 bits (0777) as
the file permission bits.
The following mask values are defined for the file type:
S_IFMT 0170000 bit mask for the file type bit field
S_IFSOCK 0140000 socket
S_IFLNK 0120000 symbolic link
S_IFREG 0100000 regular file
S_IFBLK 0060000 block device
S_IFDIR 0040000 directory
S_IFCHR 0020000 character device
S_IFIFO 0010000 FIFO
Thus, to test for a regular file (for example), one could write:
stat(pathname, &sb);
if ((sb.st_mode & S_IFMT) == S_IFREG) {
/* Handle regular file */
}
Because tests of the above form are common, additional macros are
defined by POSIX to allow the test of the file type in st_mode to be
written more concisely:
S_ISREG(m) is it a regular file?
S_ISDIR(m) directory?
S_ISCHR(m) character device?
S_ISBLK(m) block device?
S_ISFIFO(m) FIFO (named pipe)?
S_ISLNK(m) symbolic link? (Not in POSIX.1-1996.)
S_ISSOCK(m) socket? (Not in POSIX.1-1996.)
The preceding code snippet could thus be rewritten as:
stat(pathname, &sb);
if (S_ISREG(sb.st_mode)) {
/* Handle regular file */
}
The definitions of most of the above file type test macros are provided
if any of the following feature test macros is defined: _BSD_SOURCE (in
glibc 2.19 and earlier), _SVID_SOURCE (in glibc 2.19 and earlier), or
_DEFAULT_SOURCE (in glibc 2.20 and later). In addition, definitions of
all of the above macros except S_IFSOCK and S_ISSOCK() are provided if
_XOPEN_SOURCE is defined.
The definition of S_IFSOCK can also be exposed either by defining
_XOPEN_SOURCE with a value of 500 or greater or (since glibc 2.24) by
defining both _XOPEN_SOURCE and _XOPEN_SOURCE_EXTENDED.
The definition of S_ISSOCK() is exposed if any of the following feature
test macros is defined: _BSD_SOURCE (in glibc 2.19 and earlier),
_DEFAULT_SOURCE (in glibc 2.20 and later), _XOPEN_SOURCE with a value
of 500 or greater, _POSIX_C_SOURCE with a value of 200112L or greater,
or (since glibc 2.24) by defining both _XOPEN_SOURCE and
_XOPEN_SOURCE_EXTENDED.
The following mask values are defined for the file mode component of
the st_mode field:
S_ISUID 04000 set-user-ID bit
S_ISGID 02000 set-group-ID bit (see below)
S_ISVTX 01000 sticky bit (see below)
S_IRWXU 00700 owner has read, write, and execute permission
S_IRUSR 00400 owner has read permission
S_IWUSR 00200 owner has write permission
S_IXUSR 00100 owner has execute permission
S_IRWXG 00070 group has read, write, and execute permission
S_IRGRP 00040 group has read permission
S_IWGRP 00020 group has write permission
S_IXGRP 00010 group has execute permission
S_IRWXO 00007 others (not in group) have read, write, and
execute permission
S_IROTH 00004 others have read permission
S_IWOTH 00002 others have write permission
S_IXOTH 00001 others have execute permission
The set-group-ID bit (S_ISGID) has several special uses. For a direc‐
tory, it indicates that BSD semantics is to be used for that directory:
files created there inherit their group ID from the directory, not from
the effective group ID of the creating process, and directories created
there will also get the S_ISGID bit set. For a file that does not have
the group execution bit (S_IXGRP) set, the set-group-ID bit indicates
mandatory file/record locking.
The sticky bit (S_ISVTX) on a directory means that a file in that
directory can be renamed or deleted only by the owner of the file, by
the owner of the directory, and by a privileged process.
CONFORMING TO
If you need to obtain the definition of the blkcnt_t or blksize_t types
from <sys/stat.h>, then define _XOPEN_SOURCE with the value 500 or
greater (before including any header files).
POSIX.1-1990 did not describe the S_IFMT, S_IFSOCK, S_IFLNK, S_IFREG,
S_IFBLK, S_IFDIR, S_IFCHR, S_IFIFO, S_ISVTX constants, but instead
specified the use of the macros S_ISDIR(), and so on. The S_IF* con‐
stants are present in POSIX.1-2001 and later.
The S_ISLNK() and S_ISSOCK() macros were not in POSIX.1-1996, but both
are present in POSIX.1-2001; the former is from SVID 4, the latter from
SUSv2.
UNIX V7 (and later systems) had S_IREAD, S_IWRITE, S_IEXEC, where POSIX
prescribes the synonyms S_IRUSR, S_IWUSR, S_IXUSR.
NOTES
For pseudofiles that are autogenerated by the kernel, the file size
(stat.st_size; statx.stx_size) reported by the kernel is not accurate.
For example, the value 0 is returned for many files under the /proc
directory, while various files under /sys report a size of 4096 bytes,
even though the file content is smaller. For such files, one should
simply try to read as many bytes as possible (and append '\0' to the
returned buffer if it is to be interpreted as a string). st_atimensec.
SEE ALSOstat(1), stat(2), statx(2), symlink(7)COLOPHON
This page is part of release 4.14 of the Linux man-pages project. A
description of the project, information about reporting bugs, and the
latest version of this page, can be found at
https://www.kernel.org/doc/man-pages/.
Linux 2017-09-15 INODE(7)
