inode

Description

Each file has an inode containing metadata about the file. An application 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 associated with, the file inode, with the names of the corresponding structure 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 identified by the combination of its major ID (which identifies the general class of device) and minor ID (which identifies a specific instance in the general class).

Inode number

stat.st_ino; statx.stx_ino

Each file in a filesystem has a unique inode number. Inode numbers 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. Additional 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 member of the stat structure is not defined by the standard. On many  implementations it is 512 bytes; on a few systems, a different 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 interfaces, such as mmap(2), may or may not update the atime timestamp

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_mtime; 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.).

The timestamp fields report time measured with a zero point at the Epoch, 1970-01-02 00:00:00 +0000, UTC (see time(7)).

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. In order to return timestamps with nanosecond precision, the timestamp fields in the stat and statx structures are defined as structures that include a nanosecond component. See stat(2) and statx(2) for details. On filesystems that do not support subsecond timestamps, the nanosecond fields in the stat and statx structures are returned with the value 0.

stat(pathname, &sb);
if ((sb.st_mode & S_IFMT) == S_IFREG) {
    /* Handle regular file */
}

stat(pathname, &sb);
if (S_ISREG(sb.st_mode)) {
    /* Handle regular file */
}

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* constants 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).

See Also

stat(1), stat(2), statx(2), symlink(7)

Colophon

This page is part of release 5.04 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/.

Referenced By

chmod(2), fsync(2), getdents(2), mkdir(2), mknod(2), open(2), stat(2), statx(2), systemd.exec(5), truncate(2), umask(2), utime(2), utimensat(2).