mirror of https://github.com/mkerrisk/man-pages
356 lines
10 KiB
Plaintext
356 lines
10 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "<sys/stat.h>" P 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 .
|