diff options
Diffstat (limited to 'man/man7/inode.7')
| -rw-r--r-- | man/man7/inode.7 | 480 |
1 files changed, 480 insertions, 0 deletions
diff --git a/man/man7/inode.7 b/man/man7/inode.7 new file mode 100644 index 000000000..45bf71467 --- /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 (date) "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) |