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
13 sys/stat.h — data returned by the stat() function
14
16 #include <sys/stat.h>
17
19 The <sys/stat.h> header shall define the structure of the data returned
20 by the fstat(), lstat(), and stat() functions.
21 The <sys/stat.h> header shall define the stat structure, which shall
23 include at least the following members:
24 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‐2008.
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);
172 int fchmod(int, mode_t);
173 int fchmodat(int, const char *, mode_t, int);
174 int fstat(int, struct stat *);
175 int fstatat(int, const char *restrict, struct stat *restrict, int);
176 int futimens(int, const struct timespec [2]);
177 int lstat(const char *restrict, struct stat *restrict);
178 int mkdir(const char *, mode_t);
179 int mkdirat(int, const char *, mode_t);
180 int mkfifo(const char *, mode_t);
181 int mkfifoat(int, const char *, mode_t);
182 int mknod(const char *, mode_t, dev_t);
183 int mknodat(int, const char *, mode_t, dev_t);
184 int stat(const char *restrict, struct stat *restrict);
185 mode_t umask(mode_t);
186 int utimensat(int, const char *, const struct timespec [2], int);
187 The following sections are informative.
189
191 Use of the macros is recommended for determining the type of a file.
192
194 A conforming C-language application must include <sys/stat.h> for func‐
195 tions that have arguments or return values of type mode_t, so that sym‐
196 bolic values for that type can be used. An alternative would be to
197 require that these constants are also defined by including
198 <sys/types.h>.
199 The S_ISUID and S_ISGID bits may be cleared on any write, not just on
201 open(), as some historical implementations do.
202 System calls that update the time entry fields in the stat structure
204 must be documented by the implementors. POSIX-conforming systems should
205 not update the time entry fields for functions listed in the System
206 Interfaces volume of POSIX.1‐2008 unless the standard requires that
207 they do, except in the case of documented extensions to the standard.
208 Upon assignment, file timestamps are immediately converted to the reso‐
210 lution of the file system by truncation (i.e., the recorded time can be
211 older than the actual time). For example, if the file system resolution
212 is 1 microsecond, then a conforming stat() must always return an
213 st_mtim.tv_nsec that is a multiple of 1000. Some older implementations
214 returned higher-resolution timestamps while the inode information was
215 cached, and then spontaneously truncated the tv_nsec fields when they
216 were stored to and retrieved from disk, but this behavior does not con‐
217 form.
218 Note that st_dev must be unique within a Local Area Network (LAN) in a
220 ``system'' made up of multiple computers' file systems connected by a
221 LAN.
222 Networked implementations of a POSIX-conforming system must guarantee
224 that all files visible within the file tree (including parts of the
225 tree that may be remotely mounted from other machines on the network)
226 on each individual processor are uniquely identified by the combination
227 of the st_ino and st_dev fields.
228 The unit for the st_blocks member of the stat structure is not defined
230 within POSIX.1‐2008. In some implementations it is 512 bytes. It may
231 differ on a file system basis. There is no correlation between values
232 of the st_blocks and st_blksize, and the f_bsize (from <sys/statvfs.h>)
233 structure members.
234 Traditionally, some implementations defined the multiplier for
236 st_blocks in <sys/param.h> as the symbol DEV_BSIZE.
237 Some earlier versions of this standard did not specify values for the
239 file mode bit macros. The expectation was that some implementors might
240 choose to use a different encoding for these bits than the traditional
241 one, and that new applications would use symbolic file modes instead of
242 numeric. This version of the standard specifies the traditional encod‐
243 ing, in recognition that nearly 20 years after the first publication of
244 this standard numeric file modes are still in widespread use by appli‐
245 cation developers, and that all conforming implementations still use
246 the traditional encoding.
247
249 No new S_IFMT symbolic names for the file type values of mode_t will be
250 defined by POSIX.1‐2008; if new file types are required, they will only
251 be testable through S_ISxx() or S_TYPEISxxx() macros instead.
252
254 <sys_statvfs.h>, <sys_types.h>, <time.h>
255 The System Interfaces volume of POSIX.1‐2008, chmod(), fchmod(),
257 fstat(), fstatat(), futimens(), mkdir(), mkfifo(), mknod(), umask()
258
260 Portions of this text are reprinted and reproduced in electronic form
261 from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
262 -- Portable Operating System Interface (POSIX), The Open Group Base
263 Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
264 cal and Electronics Engineers, Inc and The Open Group. (This is
265 POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) In the
266 event of any discrepancy between this version and the original IEEE and
267 The Open Group Standard, the original IEEE and The Open Group Standard
268 is the referee document. The original Standard can be obtained online
269 at http://www.unix.org/online.html .
270 Any typographical or formatting errors that appear in this page are
272 most likely to have been introduced during the conversion of the source
273 files to man page format. To report such errors, see https://www.ker‐
274 nel.org/doc/man-pages/reporting_bugs.html .
275IEEE/The Open Group 2013 sys_stat.h(0P)