inode - file inode information
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.
The
stat.st_mode field (for
statx(2), the
statx.stx_mode
field) contains 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 (see execve(2)) |
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 directory,
it indicates that BSD semantics are 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 an executable file, the set-group-ID
bit causes the effective group ID of a process that executes the file to
change as described in
execve(2). 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.
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.
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).
stat(1),
stat(2),
statx(2),
symlink(7)