Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 480 insertions, 0 deletions

diff --git a/man/man7/inode.7 b/man/man7/inode.7
new file mode 100644
index 0000000..a95332f
--- /dev/null
+++ b/man/man7/inode.7
@@ -0,0 +1,480 @@
+'\" t
+.\" Copyright (c) 2017 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH inode 7 2024-05-02 "Linux man-pages (unreleased)"
+.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.
+.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
+.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
+\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_blocks\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
+.B 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.).
+.P
+The timestamp fields report time measured with a zero point at the
+.IR Epoch ,
+1970-01-01 00:00:00 +0000, UTC (see
+.BR time (7)).
+.P
+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.
+.P
+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
+.I file mode bits
+and the least significant 9 bits (0777) as the
+.IR "file permission bits" .
+.P
+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
+.P
+Thus, to test for a regular file (for example), one could write:
+.P
+.in +4n
+.EX
+stat(pathname, &sb);
+if ((sb.st_mode & S_IFMT) == S_IFREG) {
+    /* Handle regular file */
+}
+.EE
+.in
+.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
+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
+.P
+The preceding code snippet could thus be rewritten as:
+.P
+.in +4n
+.EX
+stat(pathname, &sb);
+if (S_ISREG(sb.st_mode)) {
+    /* Handle regular file */
+}
+.EE
+.in
+.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
+(in glibc 2.19 and earlier),
+.B _SVID_SOURCE
+(in glibc 2.19 and earlier),
+or
+.B _DEFAULT_SOURCE
+(in glibc 2.20 and later).
+In addition, definitions of all of the above macros except
+.B S_IFSOCK
+and
+.BR S_ISSOCK ()
+are provided if
+.B _XOPEN_SOURCE
+is defined.
+.P
+The definition of
+.B S_IFSOCK
+can also be exposed either by defining
+.B _XOPEN_SOURCE
+with a value of 500 or greater or (since glibc 2.24) by defining both
+.B _XOPEN_SOURCE
+and
+.BR _XOPEN_SOURCE_EXTENDED .
+.P
+The definition of
+.BR S_ISSOCK ()
+is exposed if any of the following feature test macros is defined:
+.B _BSD_SOURCE
+(in glibc 2.19 and earlier),
+.B _DEFAULT_SOURCE
+(in glibc 2.20 and later),
+.B _XOPEN_SOURCE
+with a value of 500 or greater,
+.B _POSIX_C_SOURCE
+with a value of 200112L or greater, or (since glibc 2.24) by defining both
+.B _XOPEN_SOURCE
+and
+.BR _XOPEN_SOURCE_EXTENDED .
+.P
+The following mask values are defined for
+the file mode component of the
+.I st_mode
+field:
+.in +4n
+.TS
+lB l lx.
+S_ISUID	  04000	T{
+set-user-ID bit (see \fBexecve\fP(2))
+T}
+S_ISGID	  02000	T{
+set-group-ID bit (see below)
+T}
+S_ISVTX	  01000	T{
+sticky bit (see below)
+T}
+
+S_IRWXU	  00700	T{
+owner has read, write, and execute permission
+T}
+S_IRUSR	  00400	T{
+owner has read permission
+T}
+S_IWUSR	  00200	T{
+owner has write permission
+T}
+S_IXUSR	  00100	T{
+owner has execute permission
+T}
+
+S_IRWXG	  00070	T{
+group has read, write, and execute permission
+T}
+S_IRGRP	  00040	T{
+group has read permission
+T}
+S_IWGRP	  00020	T{
+group has write permission
+T}
+S_IXGRP	  00010	T{
+group has execute permission
+T}
+
+S_IRWXO	  00007	T{
+others (not in group) have read, write, and execute permission
+T}
+S_IROTH	  00004	T{
+others have read permission
+T}
+S_IWOTH	  00002	T{
+others have write permission
+T}
+S_IXOTH	  00001	T{
+others have execute permission
+T}
+.TE
+.in
+.P
+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.
+.P
+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 STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+POSIX.1-2001.
+.P
+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 ,
+and
+.B S_ISVTX
+constants, but instead specified the use of
+the macros
+.BR S_ISDIR ()
+and so on.
+.P
+The
+.BR S_ISLNK ()
+and
+.BR S_ISSOCK ()
+macros were not in
+POSIX.1-1996;
+the former is from SVID 4, the latter from SUSv2.
+.P
+UNIX\ V7 (and later systems) had
+.BR S_IREAD ,
+.BR S_IWRITE ,
+.BR S_IEXEC ,
+and
+where POSIX
+prescribes the synonyms
+.BR S_IRUSR ,
+.BR S_IWUSR ,
+and
+.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
+.I /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)