stat(5)
NAME
sys/stat.h − data returned by the stat() function
SYNOPSIS
#include <sys/stat.h>
DESCRIPTION
The <sys/stat.h> header defines the structure of the data returned by the functions fstat(), lstat(), and stat(). The structure stat contains at least the following members:
| dev_t | st_dev | 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 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 | file size in bytes (if file is a regular file) |
| time_t | st_atime | time of last access |
| time_t | st_mtime | time of last data modification |
| time_t | st_ctime | time of last status change |
| long | st_blksize | a filesystem-specific preferred I/O block size for this object. In some filesystem types, this may vary from file to file |
| long | st_blocks | number of blocks of a filesystem−specific size allocated for this object |
File serial number and device ID taken together uniquely identify the file within the system. The dev_t, ino_t, mode_t, nlink_t, uid_t, gid_t, off_t, and time_t types are defined as described in <sys/types.h>. Times are given in seconds since the Epoch.
The following symbolic names for the values of st_mode are also defined:
File type:
| 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 |
File mode bits:
| S_IRWXU | read, write, execute/search by owner |
| S_IRUSR | read permission, owner |
| S_IWUSR | write permission, owner |
| S_IXUSR | execute/search permission, owner |
| S_IRWXG | read, write, execute/search by group |
| S_IRGRP | read permission, group |
| S_IWGRP | write permission, group |
| S_IXGRP | execute/search permission, group |
| S_IRWXO | read, write, execute/search by others |
| S_IROTH | read permission, others |
| S_IWOTH | write permission, others |
| S_IXOTH | execute/search permission, others |
| S_ISUID | set-user-ID on execution |
| S_ISGID | set-group-ID on execution |
| S_ISVTX | on directories, restricted deletion flag |
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 are unique. S_IRWXU is the bitwise OR of S_IRUSR, S_IWUSR, and S_IXUSR. S_IRWXG is the bitwise OR of S_IRGRP, S_IWGRP, and S_IXGRP. S_IRWXO is the bitwise OR of S_IROTH, S_IWOTH, and S_IXOTH.
Implementations may OR other implementation−dependent bitsinto S_IRWXU, S_IRWXG, and S_IRWXO, but they will not overlap any of the other bits defined in this document. The file permission bits are defined to be those corresponding to the bitwise inclusive OR of S_IRWXU, S_IRWXG, and S_IRWXO.
The following macros will 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 evaluates 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. |
The following are declared as functions and may also be defined as macros:
| int | chmod(const char *path, mode_t mode); |
| int | lstat(const char *path, struct stat *buf); |
| int | mkdir(const char *path, mode_t mode); |
| int | mkfifo(const char *path, mode_t mode); |
| int | mknod(const char *path, mode_t mode, dev_t dev); |
| int | stat(const char *path, struct stat *buf); |
| mode_t | umask(mode_t cmask); |
APPLICATION USAGE
Use of the macros is recommended for determining the type of a file.
SEE ALSO
chmod(), fchmod(), fstat(), lstat(), mkdir(), mkfifo(), mknod(), stat(), umask(), <sys/types.h>.
CHANGE HISTORY
First released in Issue 1.
Derived from Issue 1 of the SVID.
Issue 4
The following changes are incorporated for alignment with the ISO POSIX−1 standard:
• The function declarations in this header are expanded to full ISO C prototypes.
• The DESCRIPTION section is expanded to indicate (a) how files are uniquely identified within the system, (b) that times are given in units of seconds since the Epoch, (c) rules governing the definition and use of the file mode bits, and (d) usage of the file type test macros.
Other changes are incorporated as follows:
• Reference to the header <sys/types.h> is added for the definitions of dev_t, ino_t, mode_t, nlink_t, uid_t, gid_t, off_t, and time_t. This has been marked as an extension.
• References to the S_IREAD, S_IWRITE, S_IEXEC file and S_ISVTX modes are removed.
• The descriptions of the members of the stat structure in the DESCRIPTION section are corrected.
Issue 4, Version 2
The following changes are incorporated for X/OPEN UNIX conformance:
• The st_blksize and st_blocks members are added to the stat structure.
• The S_IFLINK value of S_IFMT is defined.
• The S_ISVTX file mode bit and the S_ISLNK file type test macro is defined.
• The fchmod(), lstat(), and mknod() functions are added to the list of functions declared in this header.
HP−UX EXTENSIONS
NAME
stat.h − file-specific information
DESCRIPTION
The contents of the stat structure include the following members:
ushort st_fstype; /*Type of filesystem this file */
/* is in; see vfsmount(2) */
dev_tst_realdev; /* Real device number of device */
/* containing the inode for this file */
The following symbolic names for the values of the st_mode field are defined as indicated:
File type:
| S_IFMT | 0170000 | type of file |
| S_IFSOCK | 0140000 | socket |
| S_IFLNK | 0120000 | symbolic link |
| S_IFNWK | 0110000 | network special |
| S_IFREG | 0100000 | regular (ordinary) |
| S_IFBLK | 0060000 | block special |
| S_IFDIR | 0040000 | directory |
| S_IFCHR | 0020000 | character special |
| S_IFIFO | 0010000 | FIFO special (named pipe) |
File mode bits:
File miscellaneous mode bits:
| S_CDF | 0004000 | directory is a context-dependent file |
| S_ISUID | 0004000 | set user id on execution |
| S_ISGID | 0002000 | set group id on execution |
| S_ENFMT | 0002000 | set file-locking mode to enforced |
| S_ISVTX | 0001000 | save swapped text even after use |
File permission mode bits:
| S_IRWXU | 0000700 | owner’s file access permission bits |
| S_IRUSR | 0000400 | read access permission for owner |
| S_IWUSR | 0000200 | write access permission for owner |
| S_IXUSR | 0000100 | execute/search access permission for owner |
| S_IRWXG | 0000070 | group’s file access permission bits |
| S_IRGRP | 0000040 | read access permission for group |
| S_IWGRP | 0000020 | write access permission for group |
| S_IXGRP | 0000010 | execute/search access permission for group |
| S_IRWXO | 0000007 | others’ access permission bits |
| S_IROTH | 0000004 | read access permission for others |
| S_IWOTH | 0000002 | write access permission for others |
| S_IXOTH | 0000001 | execute/search access permission for others |
Obsolete names for file permission mode bits:
| S_IREAD | 0000400 | read access permission for owner |
| S_IWRITE | 0000200 | write access permission for owner |
| S_IEXEC | 0000100 | execute/search access permission for owner |
File type test macros:
| S_ISCDF(m) | test for a context-dependent file |
| S_ISNWK(m) | test for a network special |
| S_ISSOCK(m) | test for a socket |
SEE ALSO
chmod(2), chown(2), link(2), mkdir(2), mkfifo(2), mknod(2), stat(2), symlink(2), umask(2), utime(2), types(5).
STANDARDS CONFORMANCE
<sys/stat.h>: AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
Hewlett-Packard Company — HP-UX Release 10.20: July 1996