.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "<sys/stat.h>" 0P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" <sys/stat.h> 
.SH NAME
sys/stat.h \- data returned by the stat() function
.SH SYNOPSIS
.LP
\fB#include <sys/stat.h>\fP
.SH DESCRIPTION
.LP
The \fI<sys/stat.h>\fP header shall define the structure of the data
returned by the functions \fIfstat\fP(), \fIlstat\fP(), and \fIstat\fP().
.LP
The \fBstat\fP structure shall contain at least the following members:
.sp
.RS
.nf

\fBdev_t     st_dev    \fP Device ID of device containing file. \fB
ino_t     st_ino    \fP File serial number. \fB
mode_t    st_mode   \fP Mode of file (see below). \fB
nlink_t   st_nlink  \fP Number of hard links to the file. \fB
uid_t     st_uid    \fP User ID of file. \fB
gid_t     st_gid    \fP Group ID of file. \fB

dev_t     st_rdev   \fP Device ID (if file is character or block special). \fB

off_t     st_size   \fP For regular files, the file size in bytes. \fB
                    \fP For symbolic links, the length in bytes of the \fB
                    \fP pathname contained in the symbolic link. \fB

                    \fP For a shared memory object, the length in bytes. \fB


                    \fP For a typed memory object, the length in bytes. \fB

                    \fP For other file types, the use of this field is \fB
                    \fP unspecified. \fB
time_t    st_atime  \fP Time of last access. \fB
time_t    st_mtime  \fP Time of last data modification. \fB
time_t    st_ctime  \fP Time of last status change. \fB

blksize_t st_blksize\fP A file system-specific preferred I/O block size for \fB
                    \fP this object. In some file system types, this may \fB
                    \fP vary from file to file. \fB
blkcnt_t  st_blocks \fP Number of blocks allocated for this object. \fB

\fP
.fi
.RE
.LP
The \fIst_ino\fP and \fIst_dev\fP fields taken together uniquely identify
the file within the system. The \fBblkcnt_t\fP,
\fBblksize_t\fP, \fBdev_t\fP, \fBino_t\fP, \fBmode_t\fP, \fBnlink_t\fP,
\fBuid_t\fP, \fBgid_t\fP, \fBoff_t\fP, and
\fBtime_t\fP types shall be defined as described in \fI<sys/types.h>\fP
\&. Times
shall be given in seconds since the Epoch.
.LP
Unless otherwise specified, the structure members \fIst_mode\fP, \fIst_ino\fP,
\fIst_dev\fP, \fIst_uid\fP, \fIst_gid\fP,
\fIst_atime\fP, \fIst_ctime\fP, and \fIst_mtime\fP shall have meaningful
values for all file types defined in
IEEE\ Std\ 1003.1-2001.
.LP
For symbolic links, the \fIst_mode\fP member shall contain meaningful
information, which can be used with the file type macros
described below, that take a \fImode\fP argument. The \fIst_size\fP
member shall contain the length, in bytes, of the pathname
contained in the symbolic link. File mode bits and the contents of
the remaining members of the \fBstat\fP structure are
unspecified. The value returned in the \fIst_size\fP field shall be
the length of the contents of the symbolic link, and shall not
count a trailing null if one is present.
.LP
The following symbolic names for the values of type \fBmode_t\fP shall
also be defined.
.LP
File type:
.TP 7
S_IFMT
Type of file. 
.TP 7
S_IFBLK
.RS
Block special.
.RE
.TP 7
S_IFCHR
.RS
Character special.
.RE
.TP 7
S_IFIFO
.RS
FIFO special.
.RE
.TP 7
S_IFREG
.RS
Regular.
.RE
.TP 7
S_IFDIR
.RS
Directory.
.RE
.TP 7
S_IFLNK
.RS
Symbolic link.
.RE
.TP 7
S_IFSOCK
.RS
Socket. 
.RE
.sp
.sp
.LP
File mode bits:
.TP 7
S_IRWXU
Read, write, execute/search by owner. 
.TP 7
S_IRUSR
.RS
Read permission, owner.
.RE
.TP 7
S_IWUSR
.RS
Write permission, owner.
.RE
.TP 7
S_IXUSR
.RS
Execute/search permission, owner.
.RE
.sp
.TP 7
S_IRWXG
Read, write, execute/search by group. 
.TP 7
S_IRGRP
.RS
Read permission, group.
.RE
.TP 7
S_IWGRP
.RS
Write permission, group.
.RE
.TP 7
S_IXGRP
.RS
Execute/search permission, group.
.RE
.sp
.TP 7
S_IRWXO
Read, write, execute/search by others. 
.TP 7
S_IROTH
.RS
Read permission, others.
.RE
.TP 7
S_IWOTH
.RS
Write permission, others.
.RE
.TP 7
S_IXOTH
.RS
Execute/search permission, others.
.RE
.sp
.TP 7
S_ISUID
Set-user-ID on execution.
.TP 7
S_ISGID
Set-group-ID on execution.
.TP 7
S_ISVTX
On directories, restricted deletion flag. 
.sp
.LP
The bits defined by S_IRUSR, S_IWUSR, S_IXUSR, S_IRGRP, S_IWGRP, S_IXGRP,
S_IROTH, S_IWOTH, S_IXOTH, S_ISUID, S_ISGID,  and
S_ISVTX shall be unique.
.LP
S_IRWXU is the bitwise-inclusive OR of S_IRUSR, S_IWUSR, and S_IXUSR.
.LP
S_IRWXG is the bitwise-inclusive OR of S_IRGRP, S_IWGRP, and S_IXGRP.
.LP
S_IRWXO is the bitwise-inclusive OR of S_IROTH, S_IWOTH, and S_IXOTH.
.LP
Implementations may OR other implementation-defined bits into S_IRWXU,
S_IRWXG, and S_IRWXO, but they shall not overlap any of
the other bits defined in this volume of IEEE\ Std\ 1003.1-2001. The
\fIfile permission bits\fP are defined to be those
corresponding to the bitwise-inclusive OR of S_IRWXU, S_IRWXG, and
S_IRWXO.
.LP
The following macros shall be provided to test whether a file is of
the specified type. The value \fIm\fP supplied to the
macros is the value of \fIst_mode\fP from a \fBstat\fP structure.
The macro shall evaluate to a non-zero value if the test is
true; 0 if the test is false.
.TP 7
S_ISBLK(\fIm\fP)
Test for a block special file.
.TP 7
S_ISCHR(\fIm\fP)
Test for a character special file.
.TP 7
S_ISDIR(\fIm\fP)
Test for a directory.
.TP 7
S_ISFIFO(\fIm\fP)
Test for a pipe or FIFO special file.
.TP 7
S_ISREG(\fIm\fP)
Test for a regular file.
.TP 7
S_ISLNK(\fIm\fP)
Test for a symbolic link.
.TP 7
S_ISSOCK(\fIm\fP)
Test for a socket.
.sp
.LP
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 \fIbuf\fP argument supplied to the
macros is a pointer to a \fBstat\fP 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 \fBstat\fP structure referenced by \fIbuf\fP. Otherwise,
the macro shall evaluate to zero.
.TP 7
S_TYPEISMQ(\fIbuf\fP)
Test for a message queue.
.TP 7
S_TYPEISSEM(\fIbuf\fP)
Test for a semaphore.
.TP 7
S_TYPEISSHM(\fIbuf\fP)
Test for a shared memory object.
.sp
.LP
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 \fIbuf\fP argument
supplied to the macros is a pointer to a \fBstat\fP 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 \fBstat\fP structure referenced by \fIbuf\fP.
Otherwise, the macro shall evaluate to zero.
.TP 7
S_TYPEISTMO(\fIbuf\fP)
Test macro for a typed memory object.
.sp
.LP
The following shall be declared as functions and may also be defined
as macros. Function prototypes shall be provided.
.sp
.RS
.nf

\fBint    chmod(const char *, mode_t);
int    fchmod(int, mode_t);
int    fstat(int, struct stat *);
int    lstat(const char *restrict, struct stat *restrict);
int    mkdir(const char *, mode_t);
int    mkfifo(const char *, mode_t);

int    mknod(const char *, mode_t, dev_t);

int    stat(const char *restrict, struct stat *restrict);
mode_t umask(mode_t);
\fP
.fi
.RE
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
Use of the macros is recommended for determining the type of a file.
.SH RATIONALE
.LP
A conforming C-language application must include \fI<sys/stat.h>\fP
for functions that have arguments or return values of
type \fBmode_t\fP, so that symbolic values for that type can be used.
An alternative would be to require that these constants are
also defined by including \fI<sys/types.h>\fP.
.LP
The S_ISUID and S_ISGID bits may be cleared on any write, not just
on \fIopen\fP(), as
some historical implementations do.
.LP
System calls that update the time entry fields in the \fBstat\fP 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
IEEE\ Std\ 1003.1-2001 unless the standard requires that they do,
except in the case of documented extensions to the
standard.
.LP
Note that \fIst_dev\fP must be unique within a Local Area Network
(LAN) in a ``system'' made up of multiple computers' file
systems connected by a LAN.
.LP
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 \fIst_ino\fP and \fIst_dev\fP
fields.
.LP
The unit for the \fIst_blocks\fP member of the \fBstat\fP structure
is not defined within IEEE\ Std\ 1003.1-2001. In
some implementations it is 512 bytes. It may differ on a file system
basis. There is no correlation between values of the
\fIst_blocks\fP and \fIst_blksize\fP, and the \fIf_bsize\fP (from
\fI<sys/statvfs.h>\fP) structure members.
.LP
Traditionally, some implementations defined the multiplier for \fIst_blocks\fP
in 
\fI<sys/param.h>\fP as the symbol DEV_BSIZE.
.SH FUTURE DIRECTIONS
.LP
No new S_IFMT symbolic names for the file type values of \fBmode_t\fP
will be defined by IEEE\ Std\ 1003.1-2001; if new
file types are required, they will only be testable through \fIS_ISxx\fP()
or \fIS_TYPEISxxx\fP() macros instead.
.SH SEE ALSO
.LP
\fI<sys/statvfs.h>\fP, \fI<sys/types.h>\fP, the System Interfaces
volume of IEEE\ Std\ 1003.1-2001, \fIchmod\fP(), \fIfchmod\fP(), \fIfstat\fP(),
\fIlstat\fP(), \fImkdir\fP(), \fImkfifo\fP(), \fImknod\fP(), \fIstat\fP(),
\fIumask\fP()
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 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 .