'\" et
.TH sys_stat.h "0P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH 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.
.\"
.SH NAME
sys/stat.h
\(em data returned by the stat(\|) function
.SH SYNOPSIS
.LP
.nf
#include <sys/stat.h>
.fi
.SH DESCRIPTION
The
.IR <sys/stat.h> 
header shall define the structure of the data returned by the
\fIfstat\fR(),
\fIlstat\fR(),
and
\fIstat\fR()
functions.
.P
The
.IR <sys/stat.h> 
header shall define the
.BR stat
structure, which shall include at least the following members:
.sp
.RS 4
.nf

dev_t st_dev            \fRDevice ID of device containing file.\fR
ino_t st_ino            \fRFile serial number.\fR
mode_t st_mode          \fRMode of file (see below).\fR
nlink_t st_nlink        \fRNumber of hard links to the file.\fR
uid_t st_uid            \fRUser ID of file.\fR
gid_t st_gid            \fRGroup ID of file.\fR
dev_t st_rdev           \fRDevice ID (if file is character or block special).\fR
off_t st_size           \fRFor regular files, the file size in bytes.\fR
                        \fRFor symbolic links, the length in bytes of the\fR
                        \fRpathname contained in the symbolic link.\fR
                        \fRFor a shared memory object, the length in bytes.\fR
                        \fRFor a typed memory object, the length in bytes.\fR
                        \fRFor other file types, the use of this field is\fR
                        \fRunspecified.\fR
struct timespec st_atim \fRLast data access timestamp.\fR
struct timespec st_mtim \fRLast data modification timestamp.\fR
struct timespec st_ctim \fRLast file status change timestamp.\fR
blksize_t st_blksize    \fRA file system-specific preferred I/O block size\fR
                        \fRfor this object. In some file system types, this\fR
                        \fRmay vary from file to file.\fR
blkcnt_t st_blocks      \fRNumber of blocks allocated for this object.\fR
.fi
.P
.RE
.P
The
.IR st_ino
and
.IR st_dev
fields taken together uniquely identify the file within the system.
.P
The
.IR <sys/stat.h> 
header shall define the
.BR blkcnt_t ,
.BR blksize_t ,
.BR dev_t ,
.BR ino_t ,
.BR mode_t ,
.BR nlink_t ,
.BR uid_t ,
.BR gid_t ,
.BR off_t ,
and
.BR time_t
types as described in
.IR <sys/types.h> .
.P
The
.IR <sys/stat.h> 
header shall define the
.BR timespec
structure as described in
.IR <time.h> .
Times shall be given in seconds since the Epoch.
.P
Which structure members have meaningful values depends on the
type of file. For further information, see the descriptions of
\fIfstat\fR(),
\fIlstat\fR(),
and
\fIstat\fR()
in the System Interfaces volume of POSIX.1\(hy2017.
.P
For compatibility with earlier versions of this standard, the
.IR st_atime
macro shall be defined with the value
.IR st_atim.tv_sec .
Similarly,
.IR st_ctime
and
.IR st_mtime
shall be defined as macros with the values
.IR st_ctim.tv_sec
and
.IR st_mtim.tv_sec ,
respectively.
.br
.P
The
.IR <sys/stat.h> 
header shall define the following symbolic constants for the
file types encoded in type
.BR mode_t .
The values shall be suitable for use in
.BR #if
preprocessing directives:
.IP S_IFMT 12
Type of file.
.RS 12 
.IP S_IFBLK 12
Block special.
.IP S_IFCHR 12
Character special.
.IP S_IFIFO 12
FIFO special.
.IP S_IFREG 12
Regular.
.IP S_IFDIR 12
Directory.
.IP S_IFLNK 12
Symbolic link.
.IP S_IFSOCK 12
Socket.
.RE
.P
The
.IR <sys/stat.h> 
header shall define the following symbolic constants for the file mode
bits encoded in type
.BR 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
\fIopen\fR()
without the need for a
.BR mode_t
cast. The values shall be suitable for use in
.BR #if
preprocessing directives.
.TS
center box tab(@);
cB | cB | cB
l | n | l.
Name@Numeric Value@Description
_
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.\0\0\0\*?
.TE
.P
The following macros shall be provided to test whether a file is of the
specified type. The value
.IR m
supplied to the macros is the value of
.IR st_mode
from a
.BR stat
structure. The macro shall evaluate to a non-zero value if the test is
true; 0 if the test is false.
.IP "S_ISBLK(\fIm\fP)" 14
Test for a block special file.
.IP "S_ISCHR(\fIm\fP)" 14
Test for a character special file.
.IP "S_ISDIR(\fIm\fP)" 14
Test for a directory.
.IP "S_ISFIFO(\fIm\fP)" 14
Test for a pipe or FIFO special file.
.IP "S_ISREG(\fIm\fP)" 14
Test for a regular file.
.IP "S_ISLNK(\fIm\fP)" 14
Test for a symbolic link.
.IP "S_ISSOCK(\fIm\fP)" 14
Test for a socket.
.P
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
.IR buf
argument supplied to the macros is a pointer to a
.BR 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
.BR stat
structure referenced by
.IR buf .
Otherwise, the macro shall evaluate to zero.
.IP "S_TYPEISMQ(\fIbuf\fP)" 14
Test for a message queue.
.IP "S_TYPEISSEM(\fIbuf\fP)" 14
Test for a semaphore.
.IP "S_TYPEISSHM(\fIbuf\fP)" 14
Test for a shared memory object.
.P
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
.IR buf
argument supplied to the macros is a pointer to a
.BR 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
.BR stat
structure referenced by
.IR buf .
Otherwise, the macro shall evaluate to zero.
.IP "S_TYPEISTMO(\fIbuf\fP)" 14
Test macro for a typed memory object.
.P
The
.IR <sys/stat.h> 
header shall define the following symbolic constants as distinct
integer values outside of the range [0,999\|999\|999],
for use with the
\fIfutimens\fR()
and
\fIutimensat\fR()
functions:
UTIME_NOW
UTIME_OMIT
.P
The following shall be declared as functions and may also be defined
as macros. Function prototypes shall be provided.
.sp
.RS 4
.nf

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);
.fi
.P
.RE
.P
Inclusion of the
.IR <sys/stat.h> 
header may make visible all symbols from the
.IR <time.h> 
header.
.LP
.IR "The following sections are informative."
.SH "APPLICATION USAGE"
Use of the macros is recommended for determining the type of a file.
.SH RATIONALE
A conforming C-language application must include
.IR <sys/stat.h> 
for functions that have arguments or return values of type
.BR 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
.IR <sys/types.h> .
.P
The S_ISUID and S_ISGID
bits may be cleared on any write, not just on
\fIopen\fR(),
as some historical implementations do.
.P
System calls that update the time entry fields in the
.BR 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\(hy2017 unless the standard requires that they do, except in the case
of documented extensions to the standard.
.P
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
\fIstat\fR()
must always return an
.IR st_mtim.tv_nsec
that is a multiple of 1000. Some older implementations returned
higher-resolution timestamps while the
.IR inode
information was cached, and then spontaneously truncated the
.IR tv_nsec
fields when they were stored to and retrieved from disk, but this behavior
does not conform.
.P
Note that
.IR 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.
.P
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
.IR st_ino
and
.IR st_dev
fields.
.P
The unit for the
.IR st_blocks
member of the
.BR stat
structure is not defined within POSIX.1\(hy2008. In some implementations
it is 512 bytes. It may differ on a file system basis. There is no
correlation between values of the
.IR st_blocks
and
.IR st_blksize ,
and the
.IR f_bsize
(from
.IR <sys/statvfs.h> )
structure members.
.P
Traditionally, some implementations defined the multiplier for
.IR st_blocks
in
.IR <sys/param.h> 
as the symbol DEV_BSIZE.
.P
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.
.SH "FUTURE DIRECTIONS"
No new S_IFMT symbolic names for the file type values of
.BR mode_t
will be defined by POSIX.1\(hy2008; if new file types are required, they will
only be testable through
.IR S_ISxx (\|)
or
.IR S_TYPEISxxx (\|)
macros instead.
.SH "SEE ALSO"
.IR "\fB<sys_statvfs.h>\fP",
.IR "\fB<sys_types.h>\fP",
.IR "\fB<time.h>\fP"
.P
The System Interfaces volume of POSIX.1\(hy2017,
.IR "\fIchmod\fR\^(\|)",
.IR "\fIfchmod\fR\^(\|)",
.IR "\fIfstat\fR\^(\|)",
.IR "\fIfstatat\fR\^(\|)",
.IR "\fIfutimens\fR\^(\|)",
.IR "\fImkdir\fR\^(\|)",
.IR "\fImkfifo\fR\^(\|)",
.IR "\fImknod\fR\^(\|)",
.IR "\fIumask\fR\^(\|)"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
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.opengroup.org/unix/online.html .
.PP
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 .