1sys_stat.h(0P) POSIX Programmer's Manual sys_stat.h(0P)
2
6 This manual page is part of the POSIX Programmer's Manual. The Linux
7 implementation of this interface may differ (consult the corresponding
8 Linux manual page for details of Linux behavior), or the interface may
9 not be implemented on Linux.
10
12 sys/stat.h — data returned by the stat() function
13
15 #include <sys/stat.h>
16
18 The <sys/stat.h> header shall define the structure of the data returned
19 by the fstat(), lstat(), and stat() functions.
20 The <sys/stat.h> header shall define the stat structure, which shall
22 include at least the following members:
23 dev_t st_dev Device ID of device containing file.
26 ino_t st_ino File serial number.
27 mode_t st_mode Mode of file (see below).
28 nlink_t st_nlink Number of hard links to the file.
29 uid_t st_uid User ID of file.
30 gid_t st_gid Group ID of file.
31 dev_t st_rdev Device ID (if file is character or block special).
32 off_t st_size For regular files, the file size in bytes.
33 For symbolic links, the length in bytes of the
34 pathname contained in the symbolic link.
35 For a shared memory object, the length in bytes.
36 For a typed memory object, the length in bytes.
37 For other file types, the use of this field is
38 unspecified.
39 struct timespec st_atim Last data access timestamp.
40 struct timespec st_mtim Last data modification timestamp.
41 struct timespec st_ctim Last file status change timestamp.
42 blksize_t st_blksize A file system-specific preferred I/O block size
43 for this object. In some file system types, this
44 may vary from file to file.
45 blkcnt_t st_blocks Number of blocks allocated for this object.
46 The st_ino and st_dev fields taken together uniquely identify the file
48 within the system.
49 The <sys/stat.h> header shall define the blkcnt_t, blksize_t, dev_t,
51 ino_t, mode_t, nlink_t, uid_t, gid_t, off_t, and time_t types as
52 described in <sys/types.h>.
53 The <sys/stat.h> header shall define the timespec structure as
55 described in <time.h>. Times shall be given in seconds since the
56 Epoch.
57 Which structure members have meaningful values depends on the type of
59 file. For further information, see the descriptions of fstat(),
60 lstat(), and stat() in the System Interfaces volume of POSIX.1‐2017.
61 For compatibility with earlier versions of this standard, the st_atime
63 macro shall be defined with the value st_atim.tv_sec. Similarly,
64 st_ctime and st_mtime shall be defined as macros with the values
65 st_ctim.tv_sec and st_mtim.tv_sec, respectively.
66 The <sys/stat.h> header shall define the following symbolic constants
68 for the file types encoded in type mode_t. The values shall be suit‐
69 able for use in #if preprocessing directives:
70 S_IFMT Type of file.
72 S_IFBLK Block special.
74 S_IFCHR Character special.
76 S_IFIFO FIFO special.
78 S_IFREG Regular.
80 S_IFDIR Directory.
82 S_IFLNK Symbolic link.
84 S_IFSOCK Socket.
86 The <sys/stat.h> header shall define the following symbolic constants
88 for the file mode bits encoded in type mode_t, with the indicated
89 numeric values. These macros shall expand to an expression which has a
90 type that allows them to be used, either singly or OR'ed together, as
91 the third argument to open() without the need for a mode_t cast. The
92 values shall be suitable for use in #if preprocessing directives.
93 ┌────────┬───────────────┬──────────────────────────────────────────────┐
95 │ Name │ Numeric Value │ Description │
96 ├────────┼───────────────┼──────────────────────────────────────────────┤
97 │S_IRWXU │ 0700 │ Read, write, execute/search by owner. │
98 │S_IRUSR │ 0400 │ Read permission, owner. │
99 │S_IWUSR │ 0200 │ Write permission, owner. │
100 │S_IXUSR │ 0100 │ Execute/search permission, owner. │
101 ├────────┼───────────────┼──────────────────────────────────────────────┤
102 │S_IRWXG │ 070 │ Read, write, execute/search by group. │
103 │S_IRGRP │ 040 │ Read permission, group. │
104 │S_IWGRP │ 020 │ Write permission, group. │
105 │S_IXGRP │ 010 │ Execute/search permission, group. │
106 ├────────┼───────────────┼──────────────────────────────────────────────┤
107 │S_IRWXO │ 07 │ Read, write, execute/search by others. │
108 │S_IROTH │ 04 │ Read permission, others. │
109 │S_IWOTH │ 02 │ Write permission, others. │
110 │S_IXOTH │ 01 │ Execute/search permission, others. │
111 ├────────┼───────────────┼──────────────────────────────────────────────┤
112 │S_ISUID │ 04000 │ Set-user-ID on execution. │
113 │S_ISGID │ 02000 │ Set-group-ID on execution. │
114 │S_ISVTX │ 01000 │ On directories, restricted deletion flag. │
115 └────────┴───────────────┴──────────────────────────────────────────────┘
116 The following macros shall be provided to test whether a file is of the
117 specified type. The value m supplied to the macros is the value of
118 st_mode from a stat structure. The macro shall evaluate to a non-zero
119 value if the test is true; 0 if the test is false.
120 S_ISBLK(m) Test for a block special file.
122 S_ISCHR(m) Test for a character special file.
124 S_ISDIR(m) Test for a directory.
126 S_ISFIFO(m) Test for a pipe or FIFO special file.
128 S_ISREG(m) Test for a regular file.
130 S_ISLNK(m) Test for a symbolic link.
132 S_ISSOCK(m) Test for a socket.
134 The implementation may implement message queues, semaphores, or shared
136 memory objects as distinct file types. The following macros shall be
137 provided to test whether a file is of the specified type. The value of
138 the buf argument supplied to the macros is a pointer to a stat struc‐
139 ture. The macro shall evaluate to a non-zero value if the specified
140 object is implemented as a distinct file type and the specified file
141 type is contained in the stat structure referenced by buf. Otherwise,
142 the macro shall evaluate to zero.
143 S_TYPEISMQ(buf)
145 Test for a message queue.
146 S_TYPEISSEM(buf)
148 Test for a semaphore.
149 S_TYPEISSHM(buf)
151 Test for a shared memory object.
152 The implementation may implement typed memory objects as distinct file
154 types, and the following macro shall test whether a file is of the
155 specified type. The value of the buf argument supplied to the macros is
156 a pointer to a stat structure. The macro shall evaluate to a non-zero
157 value if the specified object is implemented as a distinct file type
158 and the specified file type is contained in the stat structure refer‐
159 enced by buf. Otherwise, the macro shall evaluate to zero.
160 S_TYPEISTMO(buf)
162 Test macro for a typed memory object.
163 The <sys/stat.h> header shall define the following symbolic constants
165 as distinct integer values outside of the range [0,999999999], for use
166 with the futimens() and utimensat() functions: UTIME_NOW UTIME_OMIT
167 The following shall be declared as functions and may also be defined as
169 macros. Function prototypes shall be provided.
170 int chmod(const char *, mode_t);
173 int fchmod(int, mode_t);
174 int fchmodat(int, const char *, mode_t, int);
175 int fstat(int, struct stat *);
176 int fstatat(int, const char *restrict, struct stat *restrict, int);
177 int futimens(int, const struct timespec [2]);
178 int lstat(const char *restrict, struct stat *restrict);
179 int mkdir(const char *, mode_t);
180 int mkdirat(int, const char *, mode_t);
181 int mkfifo(const char *, mode_t);
182 int mkfifoat(int, const char *, mode_t);
183 int mknod(const char *, mode_t, dev_t);
184 int mknodat(int, const char *, mode_t, dev_t);
185 int stat(const char *restrict, struct stat *restrict);
186 mode_t umask(mode_t);
187 int utimensat(int, const char *, const struct timespec [2], int);
188 Inclusion of the <sys/stat.h> header may make visible all symbols from
190 the <time.h> header.
191 The following sections are informative.
193
195 Use of the macros is recommended for determining the type of a file.
196
198 A conforming C-language application must include <sys/stat.h> for func‐
199 tions that have arguments or return values of type mode_t, so that sym‐
200 bolic values for that type can be used. An alternative would be to
201 require that these constants are also defined by including
202 <sys/types.h>.
203 The S_ISUID and S_ISGID bits may be cleared on any write, not just on
205 open(), as some historical implementations do.
206 System calls that update the time entry fields in the stat structure
208 must be documented by the implementors. POSIX-conforming systems should
209 not update the time entry fields for functions listed in the System
210 Interfaces volume of POSIX.1‐2017 unless the standard requires that
211 they do, except in the case of documented extensions to the standard.
212 Upon assignment, file timestamps are immediately converted to the reso‐
214 lution of the file system by truncation (i.e., the recorded time can be
215 older than the actual time). For example, if the file system resolution
216 is 1 microsecond, then a conforming stat() must always return an
217 st_mtim.tv_nsec that is a multiple of 1000. Some older implementations
218 returned higher-resolution timestamps while the inode information was
219 cached, and then spontaneously truncated the tv_nsec fields when they
220 were stored to and retrieved from disk, but this behavior does not con‐
221 form.
222 Note that st_dev must be unique within a Local Area Network (LAN) in a
224 ``system'' made up of multiple computers' file systems connected by a
225 LAN.
226 Networked implementations of a POSIX-conforming system must guarantee
228 that all files visible within the file tree (including parts of the
229 tree that may be remotely mounted from other machines on the network)
230 on each individual processor are uniquely identified by the combination
231 of the st_ino and st_dev fields.
232 The unit for the st_blocks member of the stat structure is not defined
234 within POSIX.1‐2008. In some implementations it is 512 bytes. It may
235 differ on a file system basis. There is no correlation between values
236 of the st_blocks and st_blksize, and the f_bsize (from <sys/statvfs.h>)
237 structure members.
238 Traditionally, some implementations defined the multiplier for
240 st_blocks in <sys/param.h> as the symbol DEV_BSIZE.
241 Some earlier versions of this standard did not specify values for the
243 file mode bit macros. The expectation was that some implementors might
244 choose to use a different encoding for these bits than the traditional
245 one, and that new applications would use symbolic file modes instead of
246 numeric. This version of the standard specifies the traditional encod‐
247 ing, in recognition that nearly 20 years after the first publication of
248 this standard numeric file modes are still in widespread use by appli‐
249 cation developers, and that all conforming implementations still use
250 the traditional encoding.
251
253 No new S_IFMT symbolic names for the file type values of mode_t will be
254 defined by POSIX.1‐2008; if new file types are required, they will only
255 be testable through S_ISxx() or S_TYPEISxxx() macros instead.
256
258 <sys_statvfs.h>, <sys_types.h>, <time.h>
259 The System Interfaces volume of POSIX.1‐2017, chmod(), fchmod(),
261 fstat(), fstatat(), futimens(), mkdir(), mkfifo(), mknod(), umask()
262
264 Portions of this text are reprinted and reproduced in electronic form
265 from IEEE Std 1003.1-2017, Standard for Information Technology -- Por‐
266 table Operating System Interface (POSIX), The Open Group Base Specifi‐
267 cations Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of
268 Electrical and Electronics Engineers, Inc and The Open Group. In the
269 event of any discrepancy between this version and the original IEEE and
270 The Open Group Standard, the original IEEE and The Open Group Standard
271 is the referee document. The original Standard can be obtained online
272 at http://www.opengroup.org/unix/online.html .
273 Any typographical or formatting errors that appear in this page are
275 most likely to have been introduced during the conversion of the source
276 files to man page format. To report such errors, see https://www.ker‐
277 nel.org/doc/man-pages/reporting_bugs.html .
278IEEE/The Open Group 2017 sys_stat.h(0P)