inode(7)



INODE(7)                   Linux Programmer's Manual                  INODE(7)

NAME
       inode - file inode information

DESCRIPTION
       Each file has an inode containing metadata about the file.  An applica-
       tion 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 asso-
       ciated with, the file inode, with the names of the corresponding struc-
       ture 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  identi-
              fied  by  the  combination of its major ID (which identifies the
              general class of device) and minor ID (which identifies  a  spe-
              cific instance in the general class).

       Inode number
              stat.st_ino; statx.stx_ino

              Each file in a filesystem has a unique inode number.  Inode num-
              bers 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.  Addi-
              tional 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  mem-
              ber  of  the  stat structure is not defined by the standard.  On
              many  implementations it is 512 bytes; on a few systems, a  dif-
              ferent  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  inter-
              faces,  such  as  mmap(2), may or may not update the atime time-
              stamp

              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 file type and mode
       The stat.st_mode field (for statx(2), the  statx.stx_mode  field)  con-
       tains 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  de-
       fined  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),  _DE-
       FAULT_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_EX-
       TENDED.

       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  direc-
       tory,  it  indicates  that BSD semantics are to be used for that direc-
       tory: files created there inherit their group ID  from  the  directory,
       not  from  the effective group ID of the creating process, and directo-
       ries created there will also get the S_ISGID  bit  set.   For  an  exe-
       cutable  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  di-
       rectory can be renamed or deleted only by the owner of the file, by the
       owner of the directory, and by a privileged process.

CONFORMING TO
       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*  con-
       stants 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.

NOTES
       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 di-
       rectory,  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).

SEE ALSO
       stat(1), stat(2), statx(2), symlink(7)

COLOPHON
       This page is part of release 5.07 of the Linux  man-pages  project.   A
       description  of  the project, information about reporting bugs, and the
       latest    version    of    this    page,    can     be     found     at
       https://www.kernel.org/doc/man-pages/.

Linux                             2019-05-09                          INODE(7)

Man(1) output converted with man2html
list of all man pages