1STAT(2) Linux Programmer's Manual STAT(2)
2
6 stat, fstat, lstat - get file status
7
9 #include <sys/types.h>
10 #include <sys/stat.h>
11 #include <unistd.h>
12 int stat(const char *path, struct stat *buf);
14 int fstat(int fd, struct stat *buf);
15 int lstat(const char *path, struct stat *buf);
16 Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
18 lstat():
20 _BSD_SOURCE || _XOPEN_SOURCE >= 500 ||
21 _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
22 || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L
23
25 These functions return information about a file. No permissions are
26 required on the file itself, but—in the case of stat() and lstat() —
27 execute (search) permission is required on all of the directories in
28 path that lead to the file.
29 stat() stats the file pointed to by path and fills in buf.
31 lstat() is identical to stat(), except that if path is a symbolic link,
33 then the link itself is stat-ed, not the file that it refers to.
34 fstat() is identical to stat(), except that the file to be stat-ed is
36 specified by the file descriptor fd.
37 All of these system calls return a stat structure, which contains the
39 following fields:
40 struct stat {
42 dev_t st_dev; /* ID of device containing file */
43 ino_t st_ino; /* inode number */
44 mode_t st_mode; /* protection */
45 nlink_t st_nlink; /* number of hard links */
46 uid_t st_uid; /* user ID of owner */
47 gid_t st_gid; /* group ID of owner */
48 dev_t st_rdev; /* device ID (if special file) */
49 off_t st_size; /* total size, in bytes */
50 blksize_t st_blksize; /* blocksize for file system I/O */
51 blkcnt_t st_blocks; /* number of 512B blocks allocated */
52 time_t st_atime; /* time of last access */
53 time_t st_mtime; /* time of last modification */
54 time_t st_ctime; /* time of last status change */
55 };
56 The st_dev field describes the device on which this file resides. (The
58 major(3) and minor(3) macros may be useful to decompose the device ID
59 in this field.)
60 The st_rdev field describes the device that this file (inode) repre‐
62 sents.
63 The st_size field gives the size of the file (if it is a regular file
65 or a symbolic link) in bytes. The size of a symbolic link is the
66 length of the pathname it contains, without a terminating null byte.
67 The st_blocks field indicates the number of blocks allocated to the
69 file, 512-byte units. (This may be smaller than st_size/512 when the
70 file has holes.)
71 The st_blksize field gives the "preferred" blocksize for efficient file
73 system I/O. (Writing to a file in smaller chunks may cause an ineffi‐
74 cient read-modify-rewrite.)
75 Not all of the Linux file systems implement all of the time fields.
77 Some file system types allow mounting in such a way that file and/or
78 directory accesses do not cause an update of the st_atime field. (See
79 noatime, nodiratime, and relatime in mount(8), and related information
80 in mount(2).) In addition, st_atime is not updated if a file is opened
81 with the O_NOATIME; see open(2).
82 The field st_atime is changed by file accesses, for example, by
84 execve(2), mknod(2), pipe(2), utime(2) and read(2) (of more than zero
85 bytes). Other routines, like mmap(2), may or may not update st_atime.
86 The field st_mtime is changed by file modifications, for example, by
88 mknod(2), truncate(2), utime(2) and write(2) (of more than zero bytes).
89 Moreover, st_mtime of a directory is changed by the creation or dele‐
90 tion of files in that directory. The st_mtime field is not changed for
91 changes in owner, group, hard link count, or mode.
92 The field st_ctime is changed by writing or by setting inode informa‐
94 tion (i.e., owner, group, link count, mode, etc.).
95 The following POSIX macros are defined to check the file type using the
97 st_mode field:
98 S_ISREG(m) is it a regular file?
100 S_ISDIR(m) directory?
102 S_ISCHR(m) character device?
104 S_ISBLK(m) block device?
106 S_ISFIFO(m) FIFO (named pipe)?
108 S_ISLNK(m) symbolic link? (Not in POSIX.1-1996.)
110 S_ISSOCK(m) socket? (Not in POSIX.1-1996.)
112 The following flags are defined for the st_mode field:
114 S_IFMT 0170000 bit mask for the file type bit fields
116 S_IFSOCK 0140000 socket
117 S_IFLNK 0120000 symbolic link
118 S_IFREG 0100000 regular file
119 S_IFBLK 0060000 block device
120 S_IFDIR 0040000 directory
121 S_IFCHR 0020000 character device
122 S_IFIFO 0010000 FIFO
123 S_ISUID 0004000 set-user-ID bit
124 S_ISGID 0002000 set-group-ID bit (see below)
125 S_ISVTX 0001000 sticky bit (see below)
126 S_IRWXU 00700 mask for file owner permissions
127 S_IRUSR 00400 owner has read permission
128 S_IWUSR 00200 owner has write permission
129 S_IXUSR 00100 owner has execute permission
130 S_IRWXG 00070 mask for group permissions
131 S_IRGRP 00040 group has read permission
132 S_IWGRP 00020 group has write permission
134 S_IXGRP 00010 group has execute permission
135 S_IRWXO 00007 mask for permissions for others (not in group)
136 S_IROTH 00004 others have read permission
137 S_IWOTH 00002 others have write permission
138 S_IXOTH 00001 others have execute permission
139 The set-group-ID bit (S_ISGID) has several special uses. For a direc‐
141 tory it indicates that BSD semantics is to be used for that directory:
142 files created there inherit their group ID from the directory, not from
143 the effective group ID of the creating process, and directories created
144 there will also get the S_ISGID bit set. For a file that does not have
145 the group execution bit (S_IXGRP) set, the set-group-ID bit indicates
146 mandatory file/record locking.
147 The sticky bit (S_ISVTX) on a directory means that a file in that
149 directory can be renamed or deleted only by the owner of the file, by
150 the owner of the directory, and by a privileged process.
151
153 On success, zero is returned. On error, -1 is returned, and errno is
154 set appropriately.
155
157 EACCES Search permission is denied for one of the directories in the
158 path prefix of path. (See also path_resolution(7).)
159 EBADF fd is bad.
161 EFAULT Bad address.
163 ELOOP Too many symbolic links encountered while traversing the path.
165 ENAMETOOLONG
167 path is too long.
168 ENOENT A component of path does not exist, or path is an empty string.
170 ENOMEM Out of memory (i.e., kernel memory).
172 ENOTDIR
174 A component of the path prefix of path is not a directory.
175 EOVERFLOW
177 path or fd refers to a file whose size, inode number, or number
178 of blocks cannot be represented in, respectively, the types
179 off_t, ino_t, or blkcnt_t. This error can occur when, for exam‐
180 ple, an application compiled on a 32-bit platform without
181 -D_FILE_OFFSET_BITS=64 calls stat() on a file whose size exceeds
182 (1<<31)-1 bytes.
183
185 These system calls conform to SVr4, 4.3BSD, POSIX.1-2001.
186 According to POSIX.1-2001, lstat() on a symbolic link need return valid
188 information only in the st_size field and the file-type component of
189 the st_mode field of the stat structure. POSIX.-2008 tightens the
190 specification, requiring lstat() to return valid information in all
191 fields except the permission bits in st_mode.
192 Use of the st_blocks and st_blksize fields may be less portable. (They
194 were introduced in BSD. The interpretation differs between systems,
195 and possibly on a single system when NFS mounts are involved.) If you
196 need to obtain the definition of the blkcnt_t or blksize_t types from
197 <sys/stat.h>, then define _XOPEN_SOURCE with the value 500 or greater
198 (before including any header files).
199 POSIX.1-1990 did not describe the S_IFMT, S_IFSOCK, S_IFLNK, S_IFREG,
201 S_IFBLK, S_IFDIR, S_IFCHR, S_IFIFO, S_ISVTX constants, but instead
202 demanded the use of the macros S_ISDIR(), etc. The S_IF* constants are
203 present in POSIX.1-2001 and later.
204 The S_ISLNK() and S_ISSOCK() macros are not in POSIX.1-1996, but both
206 are present in POSIX.1-2001; the former is from SVID 4, the latter from
207 SUSv2.
208 UNIX V7 (and later systems) had S_IREAD, S_IWRITE, S_IEXEC, where POSIX
210 prescribes the synonyms S_IRUSR, S_IWUSR, S_IXUSR.
211 Other systems
213 Values that have been (or are) in use on various systems:
214 hex name ls octal description
216 f000 S_IFMT 170000 mask for file type
217 0000 000000 SCO out-of-service inode; BSD
218 unknown type; SVID-v2 and XPG2 have
219 both 0 and 0100000 for ordinary file
220 1000 S_IFIFO p| 010000 FIFO (named pipe)
221 2000 S_IFCHR c 020000 character special (V7)
222 3000 S_IFMPC 030000 multiplexed character special (V7)
223 4000 S_IFDIR d/ 040000 directory (V7)
224 5000 S_IFNAM 050000 XENIX named special file with two
225 subtypes, distinguished by st_rdev
226 values 1, 2
227 0001 S_INSEM s 000001 XENIX semaphore subtype of IFNAM
228 0002 S_INSHD m 000002 XENIX shared data subtype of IFNAM
229 6000 S_IFBLK b 060000 block special (V7)
230 7000 S_IFMPB 070000 multiplexed block special (V7)
231 8000 S_IFREG - 100000 regular (V7)
232 9000 S_IFCMP 110000 VxFS compressed
233 9000 S_IFNWK n 110000 network special (HP-UX)
234 a000 S_IFLNK l@ 120000 symbolic link (BSD)
235 b000 S_IFSHAD 130000 Solaris shadow inode for ACL (not
236 seen by user space)
237 c000 S_IFSOCK s= 140000 socket (BSD; also "S_IFSOC" on VxFS)
238 d000 S_IFDOOR D> 150000 Solaris door
239 e000 S_IFWHT w% 160000 BSD whiteout (not used for inode)
240 0200 S_ISVTX 001000 sticky bit: save swapped text even
241 after use (V7)
242 reserved (SVID-v2)
243 On nondirectories: don't cache this
244 file (SunOS)
245 On directories: restricted deletion
246 flag (SVID-v4.2)
247 0400 S_ISGID 002000 set-group-ID on execution (V7)
248 for directories: use BSD semantics
249 for propagation of GID
250 0400 S_ENFMT 002000 System V file locking enforcement
251 (shared with S_ISGID)
252 0800 S_ISUID 004000 set-user-ID on execution (V7)
253 0800 S_CDF 004000 directory is a context dependent
254 file (HP-UX)
255 A sticky command appeared in Version 32V AT&T UNIX.
257
259 Since kernel 2.5.48, the stat structure supports nanosecond resolution
260 for the three file timestamp fields. Glibc exposes the nanosecond com‐
261 ponent of each field using names of the form st_atim.tv_nsec if the
262 _BSD_SOURCE or _SVID_SOURCE feature test macro is defined. These
263 fields are specified in POSIX.1-2008, and, starting with version 2.12,
264 glibc also exposes these field names if _POSIX_C_SOURCE is defined with
265 the value 200809L or greater, or _XOPEN_SOURCE is defined with the
266 value 700 or greater. If none of the aforementioned macros are
267 defined, then the nanosecond values are exposed with names of the form
268 st_atimensec. On file systems that do not support subsecond time‐
269 stamps, the nanosecond fields are returned with the value 0.
270 On Linux, lstat() will generally not trigger automounter action,
272 whereas stat() will (but see fstatat(2)).
273 For most files under the /proc directory, stat() does not return the
275 file size in the st_size field; instead the field is returned with the
276 value 0.
277 Underlying kernel interface
279 Over time, increases in the size of the stat structure have led to
280 three successive versions of stat(): sys_stat() (slot __NR_oldstat),
281 sys_newstat() (slot __NR_stat), and sys_stat64() (new in kernel 2.4;
282 slot __NR_stat64). The glibc stat() wrapper function hides these
283 details from applications, invoking the most recent version of the sys‐
284 tem call provided by the kernel, and repacking the returned information
285 if required for old binaries. Similar remarks apply for fstat() and
286 lstat().
287
289 The following program calls stat() and displays selected fields in the
290 returned stat structure.
291 #include <sys/types.h>
293 #include <sys/stat.h>
294 #include <time.h>
295 #include <stdio.h>
296 #include <stdlib.h>
297 int
299 main(int argc, char *argv[])
300 {
301 struct stat sb;
302 if (argc != 2) {
304 fprintf(stderr, "Usage: %s <pathname>\n", argv[0]);
305 exit(EXIT_FAILURE);
306 }
307 if (stat(argv[1], &sb) == -1) {
309 perror("stat");
310 exit(EXIT_FAILURE);
311 }
312 printf("File type: ");
314 switch (sb.st_mode & S_IFMT) {
316 case S_IFBLK: printf("block device\n"); break;
317 case S_IFCHR: printf("character device\n"); break;
318 case S_IFDIR: printf("directory\n"); break;
319 case S_IFIFO: printf("FIFO/pipe\n"); break;
320 case S_IFLNK: printf("symlink\n"); break;
321 case S_IFREG: printf("regular file\n"); break;
322 case S_IFSOCK: printf("socket\n"); break;
323 default: printf("unknown?\n"); break;
324 }
325 printf("I-node number: %ld\n", (long) sb.st_ino);
327 printf("Mode: %lo (octal)\n",
329 (unsigned long) sb.st_mode);
330 printf("Link count: %ld\n", (long) sb.st_nlink);
332 printf("Ownership: UID=%ld GID=%ld\n",
333 (long) sb.st_uid, (long) sb.st_gid);
334 printf("Preferred I/O block size: %ld bytes\n",
336 (long) sb.st_blksize);
337 printf("File size: %lld bytes\n",
338 (long long) sb.st_size);
339 printf("Blocks allocated: %lld\n",
340 (long long) sb.st_blocks);
341 printf("Last status change: %s", ctime(&sb.st_ctime));
343 printf("Last file access: %s", ctime(&sb.st_atime));
344 printf("Last file modification: %s", ctime(&sb.st_mtime));
345 exit(EXIT_SUCCESS);
347 }
348
350 access(2), chmod(2), chown(2), fstatat(2), readlink(2), utime(2), capa‐
351 bilities(7), symlink(7)
352
354 This page is part of release 3.53 of the Linux man-pages project. A
355 description of the project, and information about reporting bugs, can
356 be found at http://www.kernel.org/doc/man-pages/.
357Linux 2012-11-11 STAT(2)