mirror of https://github.com/mkerrisk/man-pages
482 lines
13 KiB
Groff
482 lines
13 KiB
Groff
'\" t
|
|
.\" Copyright (c) 2017 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.TH INODE 7 2019-05-09 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
inode \- file inode information
|
|
.SH DESCRIPTION
|
|
Each file has an inode containing metadata about the file.
|
|
An application can retrieve this metadata using
|
|
.BR stat (2)
|
|
(or related calls), which returns a
|
|
.I stat
|
|
structure, or
|
|
.BR statx (2),
|
|
which returns a
|
|
.I statx
|
|
structure.
|
|
.PP
|
|
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
|
|
.BR stat (2)
|
|
and
|
|
.BR statx (2):
|
|
.TP
|
|
Device where inode resides
|
|
\fIstat.st_dev\fP; \fIstatx.stx_dev_minor\fP and \fIstatx.stx_dev_major\fP
|
|
.IP
|
|
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).
|
|
.TP
|
|
Inode number
|
|
\fIstat.st_ino\fP; \fIstatx.stx_ino\fP
|
|
.IP
|
|
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.
|
|
.TP
|
|
File type and mode
|
|
\fIstat.st_mode\fP; \fIstatx.stx_mode\fP
|
|
.IP
|
|
See the discussion of file type and mode, below.
|
|
.TP
|
|
Link count
|
|
\fIstat.st_nlink\fP; \fIstatx.stx_nlink\fP
|
|
.IP
|
|
This field contains the number of hard links to the file.
|
|
Additional links to an existing file are created using
|
|
.BR link (2).
|
|
.TP
|
|
User ID
|
|
.I st_uid
|
|
\fIstat.st_uid\fP; \fIstatx.stx_uid\fP
|
|
.IP
|
|
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
|
|
.BR chown (2).
|
|
.TP
|
|
Group ID
|
|
\fIstat.st_gid\fP; \fIstatx.stx_gid\fP
|
|
.IP
|
|
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
|
|
.BR chown (2).
|
|
.TP
|
|
Device represented by this inode
|
|
\fIstat.st_rdev\fP; \fIstatx.stx_rdev_minor\fP and \fIstatx.stx_rdev_major\fP
|
|
.IP
|
|
If this file (inode) represents a device,
|
|
then the inode records the major and minor ID of that device.
|
|
.TP
|
|
File size
|
|
\fIstat.st_size\fP; \fIstatx.stx_size\fP
|
|
.IP
|
|
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.
|
|
.TP
|
|
Preferred block size for I/O
|
|
\fIstat.st_blksize\fP; \fIstatx.stx_blksize\fP
|
|
.IP
|
|
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.)
|
|
.TP
|
|
Number of blocks allocated to the file
|
|
\fIstat.st_blocks\fP; \fIstatx.stx_size\fP
|
|
.IP
|
|
This field indicates the number of blocks allocated to the file,
|
|
512-byte units,
|
|
(This may be smaller than
|
|
.IR st_size /512
|
|
when the file has holes.)
|
|
.IP
|
|
The POSIX.1 standard notes
|
|
.\" Rationale for sys/stat.h in POSIX.1-2008
|
|
that the unit for the
|
|
.I st_blocks
|
|
member of the
|
|
.I 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.
|
|
.TP
|
|
Last access timestamp (atime)
|
|
\fIstat.st_atime\fP; \fIstatx.stx_atime\fP
|
|
.IP
|
|
This is the file's last access timestamp.
|
|
It is changed by file accesses, for example, by
|
|
.BR execve (2),
|
|
.BR mknod (2),
|
|
.BR pipe (2),
|
|
.BR utime (2),
|
|
and
|
|
.BR read (2)
|
|
(of more than zero bytes).
|
|
Other interfaces, such as
|
|
.BR mmap (2),
|
|
may or may not update the atime timestamp
|
|
.IP
|
|
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
|
|
.IR noatime ,
|
|
.IR nodiratime ,
|
|
and
|
|
.I relatime
|
|
in
|
|
.BR mount (8),
|
|
and related information in
|
|
.BR mount (2).)
|
|
In addition, the atime timestamp
|
|
is not updated if a file is opened with the
|
|
.BR O_NOATIME
|
|
flag; see
|
|
.BR open (2).
|
|
.TP
|
|
File creation (birth) timestamp (btime)
|
|
(not returned in the \fIstat\fP structure); \fIstatx.stx_btime\fP
|
|
.IP
|
|
The file's creation timestamp.
|
|
This is set on file creation and not changed subsequently.
|
|
.IP
|
|
The btime timestamp was not historically present on UNIX systems
|
|
and is not currently supported by most Linux filesystems.
|
|
.\" FIXME Is it supported on ext4 and XFS?
|
|
.TP
|
|
Last modification timestamp (mtime)
|
|
\fIstat.st_mtime\fP; \fIstatx.stx_mtime\fP
|
|
.IP
|
|
This is the file's last modification timestamp.
|
|
It is changed by file modifications, for example, by
|
|
.BR mknod (2),
|
|
.BR truncate (2),
|
|
.BR utime (2),
|
|
and
|
|
.BR 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
|
|
.I not
|
|
changed for changes in owner, group, hard link count, or mode.
|
|
.TP
|
|
Last status change timestamp (ctime)
|
|
\fIstat.st_ctime\fP; \fIstatx.stx_ctime\fP
|
|
.IP
|
|
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.).
|
|
.PP
|
|
The timestamp fields report time measured with a zero point at the
|
|
.IR Epoch ,
|
|
1970-01-02 00:00:00 +0000, UTC (see
|
|
.BR time (7)).
|
|
.PP
|
|
Nanosecond timestamps are supported on XFS, JFS, Btrfs, and
|
|
ext4 (since Linux 2.6.23).
|
|
.\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80
|
|
Nanosecond timestamps are not supported in ext2, ext3, and Reiserfs.
|
|
In order to return timestamps with nanosecond precision,
|
|
the timestamp fields in the
|
|
.I stat
|
|
and
|
|
.I statx
|
|
structures are defined as structures that include a nanosecond component.
|
|
See
|
|
.BR stat (2)
|
|
and
|
|
.BR statx (2)
|
|
for details.
|
|
On filesystems that do not support subsecond timestamps,
|
|
the nanosecond fields in the
|
|
.I stat
|
|
and
|
|
.I statx
|
|
structures are returned with the value 0.
|
|
.\"
|
|
.SS The file type and mode
|
|
The
|
|
.I stat.st_mode
|
|
field (for
|
|
.BR statx (2),
|
|
the
|
|
.I statx.stx_mode
|
|
field) contains the file type and mode.
|
|
.PP
|
|
POSIX refers to the
|
|
.I stat.st_mode
|
|
bits corresponding to the mask
|
|
.B S_IFMT
|
|
(see below) as the
|
|
.IR "file type" ,
|
|
the 12 bits corresponding to the mask 07777 as the
|
|
.IR "file mode bits"
|
|
and the least significant 9 bits (0777) as the
|
|
.IR "file permission bits" .
|
|
.PP
|
|
The following mask values are defined for the file type:
|
|
.in +4n
|
|
.TS
|
|
lB l l.
|
|
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
|
|
.TE
|
|
.in
|
|
.PP
|
|
Thus, to test for a regular file (for example), one could write:
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
stat(pathname, &sb);
|
|
if ((sb.st_mode & S_IFMT) == S_IFREG) {
|
|
/* Handle regular file */
|
|
}
|
|
.EE
|
|
.in
|
|
.PP
|
|
Because tests of the above form are common, additional
|
|
macros are defined by POSIX to allow the test of the file type in
|
|
.I st_mode
|
|
to be written more concisely:
|
|
.RS 4
|
|
.TP 1.2i
|
|
.BR S_ISREG (m)
|
|
is it a regular file?
|
|
.TP
|
|
.BR S_ISDIR (m)
|
|
directory?
|
|
.TP
|
|
.BR S_ISCHR (m)
|
|
character device?
|
|
.TP
|
|
.BR S_ISBLK (m)
|
|
block device?
|
|
.TP
|
|
.BR S_ISFIFO (m)
|
|
FIFO (named pipe)?
|
|
.TP
|
|
.BR S_ISLNK (m)
|
|
symbolic link? (Not in POSIX.1-1996.)
|
|
.TP
|
|
.BR S_ISSOCK (m)
|
|
socket? (Not in POSIX.1-1996.)
|
|
.RE
|
|
.PP
|
|
The preceding code snippet could thus be rewritten as:
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
stat(pathname, &sb);
|
|
if (S_ISREG(sb.st_mode)) {
|
|
/* Handle regular file */
|
|
}
|
|
.EE
|
|
.in
|
|
.PP
|
|
The definitions of most of the above file type test macros
|
|
are provided if any of the following feature test macros is defined:
|
|
.BR _BSD_SOURCE
|
|
(in glibc 2.19 and earlier),
|
|
.BR _SVID_SOURCE
|
|
(in glibc 2.19 and earlier),
|
|
or
|
|
.BR _DEFAULT_SOURCE
|
|
(in glibc 2.20 and later).
|
|
In addition, definitions of all of the above macros except
|
|
.BR S_IFSOCK
|
|
and
|
|
.BR S_ISSOCK ()
|
|
are provided if
|
|
.BR _XOPEN_SOURCE
|
|
is defined.
|
|
.PP
|
|
The definition of
|
|
.BR S_IFSOCK
|
|
can also be exposed either by defining
|
|
.BR _XOPEN_SOURCE
|
|
with a value of 500 or greater or (since glibc 2.24) by defining both
|
|
.BR _XOPEN_SOURCE
|
|
and
|
|
.BR _XOPEN_SOURCE_EXTENDED .
|
|
.PP
|
|
The definition of
|
|
.BR S_ISSOCK ()
|
|
is exposed if any of the following feature test macros is defined:
|
|
.BR _BSD_SOURCE
|
|
(in glibc 2.19 and earlier),
|
|
.BR _DEFAULT_SOURCE
|
|
(in glibc 2.20 and later),
|
|
.BR _XOPEN_SOURCE
|
|
with a value of 500 or greater,
|
|
.BR _POSIX_C_SOURCE
|
|
with a value of 200112L or greater, or (since glibc 2.24) by defining both
|
|
.BR _XOPEN_SOURCE
|
|
and
|
|
.BR _XOPEN_SOURCE_EXTENDED .
|
|
.PP
|
|
The following mask values are defined for
|
|
the file mode component of the
|
|
.I st_mode
|
|
field:
|
|
.in +4n
|
|
.TS
|
|
lB l l.
|
|
S_ISUID 04000 set-user-ID bit (see \fBexecve\fP(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 T{
|
|
others (not in group) have read, write, and execute permission
|
|
T}
|
|
S_IROTH 00004 others have read permission
|
|
S_IWOTH 00002 others have write permission
|
|
S_IXOTH 00001 others have execute permission
|
|
.TE
|
|
.in
|
|
.PP
|
|
The set-group-ID bit
|
|
.RB ( 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
|
|
.B 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
|
|
.BR execve (2).
|
|
For a file that does not have the group execution bit
|
|
.RB ( S_IXGRP )
|
|
set,
|
|
the set-group-ID bit indicates mandatory file/record locking.
|
|
.PP
|
|
The sticky bit
|
|
.RB ( 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.
|
|
.SH CONFORMING TO
|
|
If you need to obtain the definition of the
|
|
.IR blkcnt_t
|
|
or
|
|
.IR blksize_t
|
|
types from
|
|
.IR <sys/stat.h> ,
|
|
then define
|
|
.BR _XOPEN_SOURCE
|
|
with the value 500 or greater (before including
|
|
.I any
|
|
header files).
|
|
.PP
|
|
POSIX.1-1990 did not describe the
|
|
.BR S_IFMT ,
|
|
.BR S_IFSOCK ,
|
|
.BR S_IFLNK ,
|
|
.BR S_IFREG ,
|
|
.BR S_IFBLK ,
|
|
.BR S_IFDIR ,
|
|
.BR S_IFCHR ,
|
|
.BR S_IFIFO ,
|
|
.B S_ISVTX
|
|
constants, but instead specified the use of
|
|
the macros
|
|
.BR S_ISDIR (),
|
|
and so on.
|
|
The
|
|
.BR S_IF*
|
|
constants are present in POSIX.1-2001 and later.
|
|
.PP
|
|
The
|
|
.BR S_ISLNK ()
|
|
and
|
|
.BR 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.
|
|
.PP
|
|
UNIX\ V7 (and later systems) had
|
|
.BR S_IREAD ,
|
|
.BR S_IWRITE ,
|
|
.BR S_IEXEC ,
|
|
where POSIX
|
|
prescribes the synonyms
|
|
.BR S_IRUSR ,
|
|
.BR S_IWUSR ,
|
|
.BR S_IXUSR .
|
|
.SH NOTES
|
|
For pseudofiles that are autogenerated by the kernel, the file size
|
|
(\fIstat.st_size\fP; \fIstatx.stx_size\fP)
|
|
reported by the kernel is not accurate.
|
|
For example, the value 0 is returned for many files under the
|
|
.I /proc
|
|
directory,
|
|
while various files under
|
|
.IR /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 \(aq\e0\(aq to the returned buffer
|
|
if it is to be interpreted as a string).
|
|
.SH SEE ALSO
|
|
.BR stat (1),
|
|
.BR stat (2),
|
|
.BR statx (2),
|
|
.BR symlink (7)
|