1<sys/stat.h>(P) POSIX Programmer's Manual <sys/stat.h>(P)
2
6 sys/stat.h - data returned by the stat() function
7
9 #include <sys/stat.h>
10
12 The <sys/stat.h> header shall define the structure of the data returned
13 by the functions fstat(), lstat(), and stat().
14 The stat structure shall contain at least the following members:
16 dev_t st_dev Device ID of device containing file.
19 ino_t st_ino File serial number.
20 mode_t st_mode Mode of file (see below).
21 nlink_t st_nlink Number of hard links to the file.
22 uid_t st_uid User ID of file.
23 gid_t st_gid Group ID of file.
24 dev_t st_rdev Device ID (if file is character or block special).
26 off_t st_size For regular files, the file size in bytes.
28 For symbolic links, the length in bytes of the
29 pathname contained in the symbolic link.
30 For a shared memory object, the length in bytes.
32 For a typed memory object, the length in bytes.
35 For other file types, the use of this field is
37 unspecified.
38 time_t st_atime Time of last access.
39 time_t st_mtime Time of last data modification.
40 time_t st_ctime Time of last status change.
41 blksize_t st_blksize A file system-specific preferred I/O block size for
43 this object. In some file system types, this may
44 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
49 within the system. The blkcnt_t, blksize_t, dev_t, ino_t, mode_t,
50 nlink_t, uid_t, gid_t, off_t, and time_t types shall be defined as
51 described in <sys/types.h> . Times shall be given in seconds since the
52 Epoch.
53 Unless otherwise specified, the structure members st_mode, st_ino,
55 st_dev, st_uid, st_gid, st_atime, st_ctime, and st_mtime shall have
56 meaningful values for all file types defined in IEEE Std 1003.1-2001.
57 For symbolic links, the st_mode member shall contain meaningful infor‐
59 mation, which can be used with the file type macros described below,
60 that take a mode argument. The st_size member shall contain the length,
61 in bytes, of the pathname contained in the symbolic link. File mode
62 bits and the contents of the remaining members of the stat structure
63 are unspecified. The value returned in the st_size field shall be the
64 length of the contents of the symbolic link, and shall not count a
65 trailing null if one is present.
66 The following symbolic names for the values of type mode_t shall also
68 be defined.
69 File type:
71 S_IFMT Type of file.
73 S_IFBLK
75 Block special.
76 S_IFCHR
78 Character special.
79 S_IFIFO
81 FIFO special.
82 S_IFREG
84 Regular.
85 S_IFDIR
87 Directory.
88 S_IFLNK
90 Symbolic link.
91 S_IFSOCK
93 Socket.
94 File mode bits:
98 S_IRWXU
100 Read, write, execute/search by owner.
101 S_IRUSR
103 Read permission, owner.
104 S_IWUSR
106 Write permission, owner.
107 S_IXUSR
109 Execute/search permission, owner.
110 S_IRWXG
113 Read, write, execute/search by group.
114 S_IRGRP
116 Read permission, group.
117 S_IWGRP
119 Write permission, group.
120 S_IXGRP
122 Execute/search permission, group.
123 S_IRWXO
126 Read, write, execute/search by others.
127 S_IROTH
129 Read permission, others.
130 S_IWOTH
132 Write permission, others.
133 S_IXOTH
135 Execute/search permission, others.
136 S_ISUID
139 Set-user-ID on execution.
140 S_ISGID
142 Set-group-ID on execution.
143 S_ISVTX
145 On directories, restricted deletion flag.
146 The bits defined by S_IRUSR, S_IWUSR, S_IXUSR, S_IRGRP, S_IWGRP,
149 S_IXGRP, S_IROTH, S_IWOTH, S_IXOTH, S_ISUID, S_ISGID, and S_ISVTX
150 shall be unique.
151 S_IRWXU is the bitwise-inclusive OR of S_IRUSR, S_IWUSR, and S_IXUSR.
153 S_IRWXG is the bitwise-inclusive OR of S_IRGRP, S_IWGRP, and S_IXGRP.
155 S_IRWXO is the bitwise-inclusive OR of S_IROTH, S_IWOTH, and S_IXOTH.
157 Implementations may OR other implementation-defined bits into S_IRWXU,
159 S_IRWXG, and S_IRWXO, but they shall not overlap any of the other bits
160 defined in this volume of IEEE Std 1003.1-2001. The file permission
161 bits are defined to be those corresponding to the bitwise-inclusive OR
162 of S_IRWXU, S_IRWXG, and S_IRWXO.
163 The following macros shall be provided to test whether a file is of the
165 specified type. The value m supplied to the macros is the value of
166 st_mode from a stat structure. The macro shall evaluate to a non-zero
167 value if the test is true; 0 if the test is false.
168 S_ISBLK(m)
170 Test for a block special file.
171 S_ISCHR(m)
173 Test for a character special file.
174 S_ISDIR(m)
176 Test for a directory.
177 S_ISFIFO(m)
179 Test for a pipe or FIFO special file.
180 S_ISREG(m)
182 Test for a regular file.
183 S_ISLNK(m)
185 Test for a symbolic link.
186 S_ISSOCK(m)
188 Test for a socket.
189 The implementation may implement message queues, semaphores, or shared
192 memory objects as distinct file types. The following macros shall be
193 provided to test whether a file is of the specified type. The value of
194 the buf argument supplied to the macros is a pointer to a stat struc‐
195 ture. The macro shall evaluate to a non-zero value if the specified
196 object is implemented as a distinct file type and the specified file
197 type is contained in the stat structure referenced by buf. Otherwise,
198 the macro shall evaluate to zero.
199 S_TYPEISMQ(buf)
201 Test for a message queue.
202 S_TYPEISSEM(buf)
204 Test for a semaphore.
205 S_TYPEISSHM(buf)
207 Test for a shared memory object.
208 The implementation may implement typed memory objects as distinct file
211 types, and the following macro shall test whether a file is of the
212 specified type. The value of the buf argument supplied to the macros is
213 a pointer to a stat structure. The macro shall evaluate to a non-zero
214 value if the specified object is implemented as a distinct file type
215 and the specified file type is contained in the stat structure refer‐
216 enced by buf. Otherwise, the macro shall evaluate to zero.
217 S_TYPEISTMO(buf)
219 Test macro for a typed memory object.
220 The following shall be declared as functions and may also be defined as
223 macros. Function prototypes shall be provided.
224 int chmod(const char *, mode_t);
227 int fchmod(int, mode_t);
228 int fstat(int, struct stat *);
229 int lstat(const char *restrict, struct stat *restrict);
230 int mkdir(const char *, mode_t);
231 int mkfifo(const char *, mode_t);
232 int mknod(const char *, mode_t, dev_t);
234 int stat(const char *restrict, struct stat *restrict);
236 mode_t umask(mode_t);
237 The following sections are informative.
239
241 Use of the macros is recommended for determining the type of a file.
242
244 A conforming C-language application must include <sys/stat.h> for func‐
245 tions that have arguments or return values of type mode_t, so that sym‐
246 bolic values for that type can be used. An alternative would be to
247 require that these constants are also defined by including
248 <sys/types.h>.
249 The S_ISUID and S_ISGID bits may be cleared on any write, not just on
251 open(), as some historical implementations do.
252 System calls that update the time entry fields in the stat structure
254 must be documented by the implementors. POSIX-conforming systems
255 should not update the time entry fields for functions listed in the
256 System Interfaces volume of IEEE Std 1003.1-2001 unless the standard
257 requires that they do, except in the case of documented extensions to
258 the standard.
259 Note that st_dev must be unique within a Local Area Network (LAN) in a
261 ``system'' made up of multiple computers' file systems connected by a
262 LAN.
263 Networked implementations of a POSIX-conforming system must guarantee
265 that all files visible within the file tree (including parts of the
266 tree that may be remotely mounted from other machines on the network)
267 on each individual processor are uniquely identified by the combination
268 of the st_ino and st_dev fields.
269 The unit for the st_blocks member of the stat structure is not defined
271 within IEEE Std 1003.1-2001. In some implementations it is 512 bytes.
272 It may differ on a file system basis. There is no correlation between
273 values of the st_blocks and st_blksize, and the f_bsize (from
274 <sys/statvfs.h>) structure members.
275 Traditionally, some implementations defined the multiplier for
277 st_blocks in <sys/param.h> as the symbol DEV_BSIZE.
278
280 No new S_IFMT symbolic names for the file type values of mode_t will be
281 defined by IEEE Std 1003.1-2001; if new file types are required, they
282 will only be testable through S_ISxx() or S_TYPEISxxx() macros instead.
283
285 <sys/statvfs.h> , <sys/types.h> , the System Interfaces volume of
286 IEEE Std 1003.1-2001, chmod(), fchmod(), fstat(), lstat(), mkdir(),
287 mkfifo(), mknod(), stat(), umask()
288
290 Portions of this text are reprinted and reproduced in electronic form
291 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
292 -- Portable Operating System Interface (POSIX), The Open Group Base
293 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
294 Electrical and Electronics Engineers, Inc and The Open Group. In the
295 event of any discrepancy between this version and the original IEEE and
296 The Open Group Standard, the original IEEE and The Open Group Standard
297 is the referee document. The original Standard can be obtained online
298 at http://www.opengroup.org/unix/online.html .
299IEEE/The Open Group 2003 <sys/stat.h>(P)