man-pages/man7/inode.7.html
2021-03-31 01:06:50 +01:00

628 lines
16 KiB
HTML

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<HTML><HEAD><TITLE>Man page of INODE</TITLE>
</HEAD><BODY>
<H1>INODE</H1>
Section: Linux Programmer's Manual (7)<BR>Updated: 2019-05-09<BR><A HREF="#index">Index</A>
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
<A NAME="lbAB">&nbsp;</A>
<H2>NAME</H2>
inode - file inode information
<A NAME="lbAC">&nbsp;</A>
<H2>DESCRIPTION</H2>
Each file has an inode containing metadata about the file.
An application can retrieve this metadata using
<B><A HREF="/cgi-bin/man/man2html?2+stat">stat</A></B>(2)
(or related calls), which returns a
<I>stat</I>
structure, or
<B><A HREF="/cgi-bin/man/man2html?2+statx">statx</A></B>(2),
which returns a
<I>statx</I>
structure.
<P>
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
<B><A HREF="/cgi-bin/man/man2html?2+stat">stat</A></B>(2)
and
<B><A HREF="/cgi-bin/man/man2html?2+statx">statx</A></B>(2):
<DL COMPACT>
<DT id="1">Device where inode resides<DD>
<I>stat.st_dev</I>; <I>statx.stx_dev_minor</I> and <I>statx.stx_dev_major</I>
<DT id="2"><DD>
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).
<DT id="3">Inode number<DD>
<I>stat.st_ino</I>; <I>statx.stx_ino</I>
<DT id="4"><DD>
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.
<DT id="5">File type and mode<DD>
<I>stat.st_mode</I>; <I>statx.stx_mode</I>
<DT id="6"><DD>
See the discussion of file type and mode, below.
<DT id="7">Link count<DD>
<I>stat.st_nlink</I>; <I>statx.stx_nlink</I>
<DT id="8"><DD>
This field contains the number of hard links to the file.
Additional links to an existing file are created using
<B><A HREF="/cgi-bin/man/man2html?2+link">link</A></B>(2).
<DT id="9">User ID<DD>
<I>st_uid</I>
<I>stat.st_uid</I>; <I>statx.stx_uid</I>
<DT id="10"><DD>
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
<B><A HREF="/cgi-bin/man/man2html?2+chown">chown</A></B>(2).
<DT id="11">Group ID<DD>
<I>stat.st_gid</I>; <I>statx.stx_gid</I>
<DT id="12"><DD>
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
<B><A HREF="/cgi-bin/man/man2html?2+chown">chown</A></B>(2).
<DT id="13">Device represented by this inode<DD>
<I>stat.st_rdev</I>; <I>statx.stx_rdev_minor</I> and <I>statx.stx_rdev_major</I>
<DT id="14"><DD>
If this file (inode) represents a device,
then the inode records the major and minor ID of that device.
<DT id="15">File size<DD>
<I>stat.st_size</I>; <I>statx.stx_size</I>
<DT id="16"><DD>
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.
<DT id="17">Preferred block size for I/O<DD>
<I>stat.st_blksize</I>; <I>statx.stx_blksize</I>
<DT id="18"><DD>
This field gives the &quot;preferred&quot; blocksize for efficient filesystem I/O.
(Writing to a file in smaller chunks may cause
an inefficient read-modify-rewrite.)
<DT id="19">Number of blocks allocated to the file<DD>
<I>stat.st_blocks</I>; <I>statx.stx_size</I>
<DT id="20"><DD>
This field indicates the number of blocks allocated to the file,
512-byte units,
(This may be smaller than
<I>st_size</I>/512
when the file has holes.)
<DT id="21"><DD>
The POSIX.1 standard notes
that the unit for the
<I>st_blocks</I>
member of the
<I>stat</I>
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.
<DT id="22">Last access timestamp (atime)<DD>
<I>stat.st_atime</I>; <I>statx.stx_atime</I>
<DT id="23"><DD>
This is the file's last access timestamp.
It is changed by file accesses, for example, by
<B><A HREF="/cgi-bin/man/man2html?2+execve">execve</A></B>(2),
<B><A HREF="/cgi-bin/man/man2html?2+mknod">mknod</A></B>(2),
<B><A HREF="/cgi-bin/man/man2html?2+pipe">pipe</A></B>(2),
<B><A HREF="/cgi-bin/man/man2html?2+utime">utime</A></B>(2),
and
<B><A HREF="/cgi-bin/man/man2html?2+read">read</A></B>(2)
(of more than zero bytes).
Other interfaces, such as
<B><A HREF="/cgi-bin/man/man2html?2+mmap">mmap</A></B>(2),
may or may not update the atime timestamp
<DT id="24"><DD>
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
<I>noatime</I>,
<I>nodiratime</I>,
and
<I>relatime</I>
in
<B><A HREF="/cgi-bin/man/man2html?8+mount">mount</A></B>(8),
and related information in
<B><A HREF="/cgi-bin/man/man2html?2+mount">mount</A></B>(2).)
In addition, the atime timestamp
is not updated if a file is opened with the
<B>O_NOATIME</B>
flag; see
<B><A HREF="/cgi-bin/man/man2html?2+open">open</A></B>(2).
<DT id="25">File creation (birth) timestamp (btime)<DD>
(not returned in the <I>stat</I> structure); <I>statx.stx_btime</I>
<DT id="26"><DD>
The file's creation timestamp.
This is set on file creation and not changed subsequently.
<DT id="27"><DD>
The btime timestamp was not historically present on UNIX systems
and is not currently supported by most Linux filesystems.
<DT id="28">Last modification timestamp (mtime)<DD>
<I>stat.st_mtime</I>; <I>statx.stx_mtime</I>
<DT id="29"><DD>
This is the file's last modification timestamp.
It is changed by file modifications, for example, by
<B><A HREF="/cgi-bin/man/man2html?2+mknod">mknod</A></B>(2),
<B><A HREF="/cgi-bin/man/man2html?2+truncate">truncate</A></B>(2),
<B><A HREF="/cgi-bin/man/man2html?2+utime">utime</A></B>(2),
and
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(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</I>
changed for changes in owner, group, hard link count, or mode.
<DT id="30">Last status change timestamp (ctime)<DD>
<I>stat.st_ctime</I>; <I>statx.stx_ctime</I>
<DT id="31"><DD>
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.).
</DL>
<P>
The timestamp fields report time measured with a zero point at the
<I>Epoch</I>,
1970-01-02 00:00:00 +0000, UTC (see
<B><A HREF="/cgi-bin/man/man2html?7+time">time</A></B>(7)).
<P>
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
<I>stat</I>
and
<I>statx</I>
structures are defined as structures that include a nanosecond component.
See
<B><A HREF="/cgi-bin/man/man2html?2+stat">stat</A></B>(2)
and
<B><A HREF="/cgi-bin/man/man2html?2+statx">statx</A></B>(2)
for details.
On filesystems that do not support subsecond timestamps,
the nanosecond fields in the
<I>stat</I>
and
<I>statx</I>
structures are returned with the value 0.
<A NAME="lbAD">&nbsp;</A>
<H3>The file type and mode</H3>
The
<I>stat.st_mode</I>
field (for
<B><A HREF="/cgi-bin/man/man2html?2+statx">statx</A></B>(2),
the
<I>statx.stx_mode</I>
field) contains the file type and mode.
<P>
POSIX refers to the
<I>stat.st_mode</I>
bits corresponding to the mask
<B>S_IFMT</B>
(see below) as the
<I>file type</I>,
the 12 bits corresponding to the mask 07777 as the
<I>file mode bits</I>
and the least significant 9 bits (0777) as the
<I>file permission bits</I>.
<P>
The following mask values are defined for the file type:
<TABLE>
<TR VALIGN=top><TD><B>S_IFMT</B></TD><TD>0170000</TD><TD>bit mask for the file type bit field<BR></TD></TR>
<TR VALIGN=top><TD><B></B></TD><TD></TD><TD><BR></TD></TR>
<TR VALIGN=top><TD><B>S_IFSOCK</B></TD><TD>0140000</TD><TD>socket<BR></TD></TR>
<TR VALIGN=top><TD><B>S_IFLNK</B></TD><TD>0120000</TD><TD>symbolic link<BR></TD></TR>
<TR VALIGN=top><TD><B>S_IFREG</B></TD><TD>0100000</TD><TD>regular file<BR></TD></TR>
<TR VALIGN=top><TD><B>S_IFBLK</B></TD><TD>0060000</TD><TD>block device<BR></TD></TR>
<TR VALIGN=top><TD><B>S_IFDIR</B></TD><TD>0040000</TD><TD>directory<BR></TD></TR>
<TR VALIGN=top><TD><B>S_IFCHR</B></TD><TD>0020000</TD><TD>character device<BR></TD></TR>
<TR VALIGN=top><TD><B>S_IFIFO</B></TD><TD>0010000</TD><TD>FIFO<BR></TD></TR>
</TABLE>
<P>
Thus, to test for a regular file (for example), one could write:
<P>
stat(pathname, &amp;sb);
if ((sb.st_mode &amp; S_IFMT) == S_IFREG) {
<BR>&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Handle&nbsp;regular&nbsp;file&nbsp;*/
}
<P>
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</I>
to be written more concisely:
<DL COMPACT><DT id="32"><DD>
<DL COMPACT>
<DT id="33"><B>S_ISREG</B>(m)
<DD>
is it a regular file?
<DT id="34"><B>S_ISDIR</B>(m)
<DD>
directory?
<DT id="35"><B>S_ISCHR</B>(m)
<DD>
character device?
<DT id="36"><B>S_ISBLK</B>(m)
<DD>
block device?
<DT id="37"><B>S_ISFIFO</B>(m)
<DD>
FIFO (named pipe)?
<DT id="38"><B>S_ISLNK</B>(m)
<DD>
symbolic link? (Not in POSIX.1-1996.)
<DT id="39"><B>S_ISSOCK</B>(m)
<DD>
socket? (Not in POSIX.1-1996.)
</DL>
</DL>
<P>
The preceding code snippet could thus be rewritten as:
<P>
stat(pathname, &amp;sb);
if (S_ISREG(sb.st_mode)) {
<BR>&nbsp;&nbsp;&nbsp;&nbsp;/*&nbsp;Handle&nbsp;regular&nbsp;file&nbsp;*/
}
<P>
The definitions of most of the above file type test macros
are provided if any of the following feature test macros is defined:
<B>_BSD_SOURCE</B>
(in glibc 2.19 and earlier),
<B>_SVID_SOURCE</B>
(in glibc 2.19 and earlier),
or
<B>_DEFAULT_SOURCE</B>
(in glibc 2.20 and later).
In addition, definitions of all of the above macros except
<B>S_IFSOCK</B>
and
<B>S_ISSOCK</B>()
are provided if
<B>_XOPEN_SOURCE</B>
is defined.
<P>
The definition of
<B>S_IFSOCK</B>
can also be exposed either by defining
<B>_XOPEN_SOURCE</B>
with a value of 500 or greater or (since glibc 2.24) by defining both
<B>_XOPEN_SOURCE</B>
and
<B>_XOPEN_SOURCE_EXTENDED</B>.
<P>
The definition of
<B>S_ISSOCK</B>()
is exposed if any of the following feature test macros is defined:
<B>_BSD_SOURCE</B>
(in glibc 2.19 and earlier),
<B>_DEFAULT_SOURCE</B>
(in glibc 2.20 and later),
<B>_XOPEN_SOURCE</B>
with a value of 500 or greater,
<B>_POSIX_C_SOURCE</B>
with a value of 200112L or greater, or (since glibc 2.24) by defining both
<B>_XOPEN_SOURCE</B>
and
<B>_XOPEN_SOURCE_EXTENDED</B>.
<P>
The following mask values are defined for
the file mode component of the
<I>st_mode</I>
field:
<TABLE>
<TR VALIGN=top><TD><B>S_ISUID</B></TD><TD> 04000</TD><TD>set-user-ID bit (see <B><A HREF="/cgi-bin/man/man2html?2+execve">execve</A></B>(2))<BR></TD></TR>
<TR VALIGN=top><TD><B>S_ISGID</B></TD><TD> 02000</TD><TD>set-group-ID bit (see below)<BR></TD></TR>
<TR VALIGN=top><TD><B>S_ISVTX</B></TD><TD> 01000</TD><TD>sticky bit (see below)<BR></TD></TR>
<TR VALIGN=top><TD><B></B></TD><TD></TD><TD><BR></TD></TR>
<TR VALIGN=top><TD><B>S_IRWXU</B></TD><TD> 00700</TD><TD>owner has read, write, and execute permission<BR></TD></TR>
<TR VALIGN=top><TD><B>S_IRUSR</B></TD><TD> 00400</TD><TD>owner has read permission<BR></TD></TR>
<TR VALIGN=top><TD><B>S_IWUSR</B></TD><TD> 00200</TD><TD>owner has write permission<BR></TD></TR>
<TR VALIGN=top><TD><B>S_IXUSR</B></TD><TD> 00100</TD><TD>owner has execute permission<BR></TD></TR>
<TR VALIGN=top><TD><B></B></TD><TD></TD><TD><BR></TD></TR>
<TR VALIGN=top><TD><B>S_IRWXG</B></TD><TD> 00070</TD><TD>group has read, write, and execute permission<BR></TD></TR>
<TR VALIGN=top><TD><B>S_IRGRP</B></TD><TD> 00040</TD><TD>group has read permission<BR></TD></TR>
<TR VALIGN=top><TD><B>S_IWGRP</B></TD><TD> 00020</TD><TD>group has write permission<BR></TD></TR>
<TR VALIGN=top><TD><B>S_IXGRP</B></TD><TD> 00010</TD><TD>group has execute permission<BR></TD></TR>
<TR VALIGN=top><TD><B></B></TD><TD></TD><TD><BR></TD></TR>
<TR VALIGN=top><TD><B>S_IRWXO</B></TD><TD> 00007</TD><TD>
others (not in group) have read, write, and execute permission
<BR></TD></TR>
<TR VALIGN=top><TD><B>S_IROTH</B></TD><TD> 00004</TD><TD>others have read permission<BR></TD></TR>
<TR VALIGN=top><TD><B>S_IWOTH</B></TD><TD> 00002</TD><TD>others have write permission<BR></TD></TR>
<TR VALIGN=top><TD><B>S_IXOTH</B></TD><TD> 00001</TD><TD>others have execute permission<BR></TD></TR>
</TABLE>
<P>
The set-group-ID bit
(<B>S_ISGID</B>)
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</B>
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
<B><A HREF="/cgi-bin/man/man2html?2+execve">execve</A></B>(2).
For a file that does not have the group execution bit
(<B>S_IXGRP</B>)
set,
the set-group-ID bit indicates mandatory file/record locking.
<P>
The sticky bit
(<B>S_ISVTX</B>)
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.
<A NAME="lbAE">&nbsp;</A>
<H2>CONFORMING TO</H2>
If you need to obtain the definition of the
<I>blkcnt_t</I>
or
<I>blksize_t</I>
types from
<I>&lt;<A HREF="file:///usr/include/sys/stat.h">sys/stat.h</A>&gt;</I>,
then define
<B>_XOPEN_SOURCE</B>
with the value 500 or greater (before including
<I>any</I>
header files).
<P>
POSIX.1-1990 did not describe the
<B>S_IFMT</B>,
<B>S_IFSOCK</B>,
<B>S_IFLNK</B>,
<B>S_IFREG</B>,
<B>S_IFBLK</B>,
<B>S_IFDIR</B>,
<B>S_IFCHR</B>,
<B>S_IFIFO</B>,
<B>S_ISVTX</B>
constants, but instead specified the use of
the macros
<B>S_ISDIR</B>(),
and so on.
The
<B>S_IF*</B>
constants are present in POSIX.1-2001 and later.
<P>
The
<B>S_ISLNK</B>()
and
<B>S_ISSOCK</B>()
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.
<P>
UNIX&nbsp;V7 (and later systems) had
<B>S_IREAD</B>,
<B>S_IWRITE</B>,
<B>S_IEXEC</B>,
where POSIX
prescribes the synonyms
<B>S_IRUSR</B>,
<B>S_IWUSR</B>,
<B>S_IXUSR</B>.
<A NAME="lbAF">&nbsp;</A>
<H2>NOTES</H2>
For pseudofiles that are autogenerated by the kernel, the file size
(<I>stat.st_size</I>; <I>statx.stx_size</I>)
reported by the kernel is not accurate.
For example, the value 0 is returned for many files under the
<I>/proc</I>
directory,
while various files under
<I>/sys</I>
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).
<A NAME="lbAG">&nbsp;</A>
<H2>SEE ALSO</H2>
<B><A HREF="/cgi-bin/man/man2html?1+stat">stat</A></B>(1),
<B><A HREF="/cgi-bin/man/man2html?2+stat">stat</A></B>(2),
<B><A HREF="/cgi-bin/man/man2html?2+statx">statx</A></B>(2),
<B><A HREF="/cgi-bin/man/man2html?7+symlink">symlink</A></B>(7)
<A NAME="lbAH">&nbsp;</A>
<H2>COLOPHON</H2>
This page is part of release 5.05 of the Linux
<I>man-pages</I>
project.
A description of the project,
information about reporting bugs,
and the latest version of this page,
can be found at
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
<P>
<HR>
<A NAME="index">&nbsp;</A><H2>Index</H2>
<DL>
<DT id="40"><A HREF="#lbAB">NAME</A><DD>
<DT id="41"><A HREF="#lbAC">DESCRIPTION</A><DD>
<DL>
<DT id="42"><A HREF="#lbAD">The file type and mode</A><DD>
</DL>
<DT id="43"><A HREF="#lbAE">CONFORMING TO</A><DD>
<DT id="44"><A HREF="#lbAF">NOTES</A><DD>
<DT id="45"><A HREF="#lbAG">SEE ALSO</A><DD>
<DT id="46"><A HREF="#lbAH">COLOPHON</A><DD>
</DL>
<HR>
This document was created by
<A HREF="/cgi-bin/man/man2html">man2html</A>,
using the manual pages.<BR>
Time: 00:06:08 GMT, March 31, 2021
</BODY>
</HTML>