Provided by: manpages-posix-dev_2013a-1_all bug

PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of
       this interface may differ (consult the corresponding Linux  manual  page  for  details  of
       Linux behavior), or the interface may not be implemented on Linux.

NAME

       sys/stat.h — data returned by the stat() function

SYNOPSIS

       #include <sys/stat.h>

DESCRIPTION

       The  <sys/stat.h>  header  shall define the structure of the data returned by the fstat(),
       lstat(), and stat() functions.

       The <sys/stat.h> header shall define the stat structure, which shall include at least  the
       following members:

           dev_t st_dev            Device ID of device containing file.
           ino_t st_ino            File serial number.
           mode_t st_mode          Mode of file (see below).
           nlink_t st_nlink        Number of hard links to the file.
           uid_t st_uid            User ID of file.
           gid_t st_gid            Group ID of file.
           dev_t st_rdev           Device ID (if file is character or block special).
           off_t st_size           For regular files, the file size in bytes.
                                   For symbolic links, the length in bytes of the
                                   pathname contained in the symbolic link.
                                   For a shared memory object, the length in bytes.
                                   For a typed memory object, the length in bytes.
                                   For other file types, the use of this field is
                                   unspecified.
           struct timespec st_atim Last data access timestamp.
           struct timespec st_mtim Last data modification timestamp.
           struct timespec st_ctim Last file status change timestamp.
           blksize_t st_blksize    A file system-specific preferred I/O block size
                                   for this object. In some file system types, this
                                   may vary from file to file.
           blkcnt_t st_blocks      Number of blocks allocated for this object.

       The st_ino and st_dev fields taken together uniquely identify the file within the system.

       The  <sys/stat.h>  header  shall  define  the  blkcnt_t,  blksize_t, dev_t, ino_t, mode_t,
       nlink_t, uid_t, gid_t, off_t, and time_t types as described in <sys/types.h>.

       The <sys/stat.h> header shall define the timespec  structure  as  described  in  <time.h>.
       Times shall be given in seconds since the Epoch.

       Which  structure  members  have meaningful values depends on the type of file. For further
       information, see the descriptions of fstat(), lstat(), and stat() in the System Interfaces
       volume of POSIX.1‐2008.

       For  compatibility  with  earlier  versions  of this standard, the st_atime macro shall be
       defined with the value st_atim.tv_sec.  Similarly, st_ctime and st_mtime shall be  defined
       as macros with the values st_ctim.tv_sec and st_mtim.tv_sec, respectively.

       The  <sys/stat.h>  header shall define the following symbolic constants for the file types
       encoded in type mode_t.  The values  shall  be  suitable  for  use  in  #if  preprocessing
       directives:

       S_IFMT      Type of file.

                   S_IFBLK     Block special.

                   S_IFCHR     Character special.

                   S_IFIFO     FIFO special.

                   S_IFREG     Regular.

                   S_IFDIR     Directory.

                   S_IFLNK     Symbolic link.

                   S_IFSOCK    Socket.

       The  <sys/stat.h>  header  shall define the following symbolic constants for the file mode
       bits encoded in type mode_t, with the indicated numeric values. These macros shall  expand
       to  an  expression  which  has  a type that allows them to be used, either singly or OR'ed
       together, as the third argument to open() without the need for a mode_t cast.  The  values
       shall be suitable for use in #if preprocessing directives.

                ┌────────┬───────────────┬──────────────────────────────────────────────┐
                │ NameNumeric ValueDescription                  │
                ├────────┼───────────────┼──────────────────────────────────────────────┤
                │S_IRWXU │      0700     │ Read, write, execute/search by owner.        │
                │S_IRUSR │      0400     │ Read permission, owner.                      │
                │S_IWUSR │      0200     │ Write permission, owner.                     │
                │S_IXUSR │      0100     │ Execute/search permission, owner.            │
                ├────────┼───────────────┼──────────────────────────────────────────────┤
                │S_IRWXG │       070     │ Read, write, execute/search by group.        │
                │S_IRGRP │       040     │ Read permission, group.                      │
                │S_IWGRP │       020     │ Write permission, group.                     │
                │S_IXGRP │       010     │ Execute/search permission, group.            │
                ├────────┼───────────────┼──────────────────────────────────────────────┤
                │S_IRWXO │        07     │ Read, write, execute/search by others.       │
                │S_IROTH │        04     │ Read permission, others.                     │
                │S_IWOTH │        02     │ Write permission, others.                    │
                │S_IXOTH │        01     │ Execute/search permission, others.           │
                ├────────┼───────────────┼──────────────────────────────────────────────┤
                │S_ISUID │     04000     │ Set-user-ID on execution.                    │
                │S_ISGID │     02000     │ Set-group-ID on execution.                   │
                │S_ISVTX │     01000     │ On directories, restricted deletion flag.    │
                └────────┴───────────────┴──────────────────────────────────────────────┘
       The  following  macros  shall be provided to test whether a file is of the specified type.
       The value m supplied to the macros is the value of st_mode  from  a  stat  structure.  The
       macro shall evaluate to a non-zero value if the test is true; 0 if the test is false.

       S_ISBLK(m)    Test for a block special file.

       S_ISCHR(m)    Test for a character special file.

       S_ISDIR(m)    Test for a directory.

       S_ISFIFO(m)   Test for a pipe or FIFO special file.

       S_ISREG(m)    Test for a regular file.

       S_ISLNK(m)    Test for a symbolic link.

       S_ISSOCK(m)   Test for a socket.

       The  implementation  may implement message queues, semaphores, or shared memory objects as
       distinct file types. The following macros shall be provided to test whether a file  is  of
       the specified type. The value of the buf argument supplied to the macros is a pointer to a
       stat structure. The macro shall evaluate to a non-zero value if the  specified  object  is
       implemented  as  a distinct file type and the specified file type is contained in the stat
       structure referenced by buf.  Otherwise, the macro shall evaluate to zero.

       S_TYPEISMQ(buf)
                     Test for a message queue.

       S_TYPEISSEM(buf)
                     Test for a semaphore.

       S_TYPEISSHM(buf)
                     Test for a shared memory object.

       The implementation may implement typed memory objects as  distinct  file  types,  and  the
       following  macro  shall test whether a file is of the specified type. The value of the buf
       argument supplied to the macros is a pointer to a stat structure. The macro shall evaluate
       to a non-zero value if the specified object is implemented as a distinct file type and the
       specified file type is contained in the stat structure referenced by buf.  Otherwise,  the
       macro shall evaluate to zero.

       S_TYPEISTMO(buf)
                     Test macro for a typed memory object.

       The  <sys/stat.h> header shall define the following symbolic constants as distinct integer
       values outside of the range [0,999999999], for use with  the  futimens()  and  utimensat()
       functions: UTIME_NOW UTIME_OMIT

       The  following  shall be declared as functions and may also be defined as macros. Function
       prototypes shall be provided.

           int    chmod(const char *, mode_t);
           int    fchmod(int, mode_t);
           int    fchmodat(int, const char *, mode_t, int);
           int    fstat(int, struct stat *);
           int    fstatat(int, const char *restrict, struct stat *restrict, int);
           int    futimens(int, const struct timespec [2]);
           int    lstat(const char *restrict, struct stat *restrict);
           int    mkdir(const char *, mode_t);
           int    mkdirat(int, const char *, mode_t);
           int    mkfifo(const char *, mode_t);
           int    mkfifoat(int, const char *, mode_t);
           int    mknod(const char *, mode_t, dev_t);
           int    mknodat(int, const char *, mode_t, dev_t);
           int    stat(const char *restrict, struct stat *restrict);
           mode_t umask(mode_t);
           int    utimensat(int, const char *, const struct timespec [2], int);

       The following sections are informative.

APPLICATION USAGE

       Use of the macros is recommended for determining the type of a file.

RATIONALE

       A conforming C-language application must include  <sys/stat.h>  for  functions  that  have
       arguments  or  return  values of type mode_t, so that symbolic values for that type can be
       used. An alternative would be  to  require  that  these  constants  are  also  defined  by
       including <sys/types.h>.

       The  S_ISUID  and  S_ISGID  bits  may be cleared on any write, not just on open(), as some
       historical implementations do.

       System calls that update the time entry fields in the stat structure must be documented by
       the  implementors.  POSIX-conforming  systems  should not update the time entry fields for
       functions listed in the System Interfaces  volume  of  POSIX.1‐2008  unless  the  standard
       requires that they do, except in the case of documented extensions to the standard.

       Upon  assignment,  file timestamps are immediately converted to the resolution of the file
       system by truncation (i.e., the recorded time can be older  than  the  actual  time).  For
       example,  if  the  file  system resolution is 1 microsecond, then a conforming stat() must
       always return an st_mtim.tv_nsec that is a multiple of 1000.  Some  older  implementations
       returned  higher-resolution  timestamps  while  the inode information was cached, and then
       spontaneously truncated the tv_nsec fields when they were stored  to  and  retrieved  from
       disk, but this behavior does not conform.

       Note  that st_dev must be unique within a Local Area Network (LAN) in a ``system'' made up
       of multiple computers' file systems connected by a LAN.

       Networked implementations of a POSIX-conforming  system  must  guarantee  that  all  files
       visible  within  the  file  tree (including parts of the tree that may be remotely mounted
       from other machines on the network) on each individual processor are  uniquely  identified
       by the combination of the st_ino and st_dev fields.

       The  unit  for  the  st_blocks  member  of  the  stat  structure  is  not  defined  within
       POSIX.1‐2008. In some implementations it is 512 bytes. It may  differ  on  a  file  system
       basis.  There  is  no  correlation between values of the st_blocks and st_blksize, and the
       f_bsize (from <sys/statvfs.h>) structure members.

       Traditionally, some implementations defined the multiplier for st_blocks in  <sys/param.h>
       as the symbol DEV_BSIZE.

       Some  earlier  versions  of  this  standard  did  not specify values for the file mode bit
       macros. The expectation was that  some  implementors  might  choose  to  use  a  different
       encoding  for  these  bits  than  the traditional one, and that new applications would use
       symbolic file modes instead of  numeric.  This  version  of  the  standard  specifies  the
       traditional  encoding,  in recognition that nearly 20 years after the first publication of
       this standard numeric file modes are still in widespread use  by  application  developers,
       and that all conforming implementations still use the traditional encoding.

FUTURE DIRECTIONS

       No  new  S_IFMT  symbolic  names  for  the  file  type values of mode_t will be defined by
       POSIX.1‐2008; if new file types are required, they will only be testable through  S_ISxx()
       or S_TYPEISxxx() macros instead.

SEE ALSO

       <sys_statvfs.h>, <sys_types.h>, <time.h>

       The  System  Interfaces  volume  of  POSIX.1‐2008,  chmod(), fchmod(), fstat(), fstatat(),
       futimens(), mkdir(), mkfifo(), mknod(), umask()

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1,  2013  Edition,  Standard  for Information Technology -- Portable Operating System
       Interface (POSIX), The Open Group Base Specifications Issue 7, Copyright (C) 2013  by  the
       Institute  of  Electrical  and  Electronics  Engineers,  Inc and The Open Group.  (This is
       POSIX.1-2008 with the  2013  Technical  Corrigendum  1  applied.)  In  the  event  of  any
       discrepancy  between  this  version and the original IEEE and The Open Group Standard, the
       original IEEE and The Open Group Standard is the referee document. The  original  Standard
       can be obtained online at http://www.unix.org/online.html .

       Any  typographical  or  formatting errors that appear in this page are most likely to have
       been introduced during the conversion of the source files to man page  format.  To  report
       such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .