sys_stat.h(0P)

PROLOG ✨

okay so bestie, this is sys_stat.h(0P) — the POSIX Programmer's Manual page for the <sys/stat.h> header. 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 🦋

okay so 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‐2017.

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.

• S_IRWXU — numeric value 0700 — Read, write, execute/search by owner.
• S_IRUSR — numeric value 0400 — Read permission, owner.
• S_IWUSR — numeric value 0200 — Write permission, owner.
• S_IXUSR — numeric value 0100 — Execute/search permission, owner.
• S_IRWXG — numeric value 070 — Read, write, execute/search by group.
• S_IRGRP — numeric value 040 — Read permission, group.
• S_IWGRP — numeric value 020 — Write permission, group.
• S_IXGRP — numeric value 010 — Execute/search permission, group.
• S_IRWXO — numeric value 07 — Read, write, execute/search by others.
• S_IROTH — numeric value 04 — Read permission, others.
• S_IWOTH — numeric value 02 — Write permission, others.
• S_IXOTH — numeric value 01 — Execute/search permission, others.
• S_ISUID — numeric value 04000 — Set-user-ID on execution.
• S_ISGID — numeric value 02000 — Set-group-ID on execution.
• S_ISVTX — numeric value 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);

Inclusion of the <sys/stat.h> header may make visible all symbols from the <time.h> header.

The following sections are informative.

---

APPLICATION USAGE 🌸

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

💖 RATIONALE 💖

ok so bestie, first thing: if you're writing a conforming C-language application and you're using functions that take arguments or return values of type mode_t, you have to include <sys/stat.h> — that's the only way you get to use the symbolic values for that type. Like, that's the whole point. An alternative could have been to require those constants to also be defined by including <sys/types.h>, but nope, that's not how they did it. 🙈

The S_ISUID and S_ISGID bits may be cleared on any write, not just on open(), like some historical implementations do. so don't be shocked, it's giving "traditionally unhinged" but it's allowed. 💅

System calls that update the time entry fields in the stat structure must be documented by the implementors. That's on them, not you. And POSIX-conforming systems should not update the time entry fields for functions listed in the System Interfaces volume of POSIX.1‐2017 unless the standard requires that they do — the one exception being documented extensions to the standard. slay, boundaries. ✨

ok now this part is iconic: upon assignment, file timestamps are immediately converted to the resolution of the file system by truncation — meaning the recorded time can be older than the actual time. yes, really. 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. That behavior does not conform. periodt. 🚫

Also 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. iykyk. 🦋

Networked implementations of a POSIX-conforming system must guarantee that all files visible within the file tree — including the 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. no cap, that's the vibe check. 🔥

Now, the unit for the st_blocks member of the stat structure is not defined within POSIX.1‐2008. In some implementations it's 512 bytes. It may differ on a file system basis. And there is no correlation between values of the st_blocks and st_blksize, and the f_bsize (from <sys/statvfs.h>) structure members. so don't try to math them together bestie, they're not friends. 💀

Traditionally, some implementations defined the multiplier for st_blocks in <sys/param.h> as the symbol DEV_BSIZE. cute little historical nugget for you. 🎀

And finally, storytime: some earlier versions of this standard did not specify values for the file mode bit macros. The expectation back then 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. the tradition ate, honestly. 👑

---

🔮 FUTURE DIRECTIONS 🔮

ok so looking ahead: 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. that's the plan, bestie, manifesting it. ✨

---

🌸 SEE ALSO 🌸

• <sys_statvfs.h>
• <sys_types.h>
• <time.h>

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

like go read those too, they're the group chat. 🫶

---

📜 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 .

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 .

---

and that's a wrap on sys_stat.h(0P) bestie!! 💖 this lil beauty comes to you from IEEE/The Open Group, dated 2017 — go forth and stat responsibly, mwah 🎀✨🦋