2 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
3 .\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95
4 .\" and Copyright (c) 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
6 .\" %%%LICENSE_START(VERBATIM)
7 .\" Permission is granted to make and distribute verbatim copies of this
8 .\" manual provided the copyright notice and this permission notice are
9 .\" preserved on all copies.
11 .\" Permission is granted to copy and distribute modified versions of this
12 .\" manual under the conditions for verbatim copying, provided that the
13 .\" entire resulting derived work is distributed under the terms of a
14 .\" permission notice identical to this one.
16 .\" Since the Linux kernel and libraries are constantly changing, this
17 .\" manual page may be incorrect or out-of-date. The author(s) assume no
18 .\" responsibility for errors or omissions, or for damages resulting from
19 .\" the use of the information contained herein. The author(s) may not
20 .\" have taken the same level of care in the production of this manual,
21 .\" which is licensed free of charge, as they might when working
24 .\" Formatted or processed versions of this manual, if unaccompanied by
25 .\" the source, must acknowledge the copyright and authors of this work.
28 .\" Modified by Michael Haardt <michael@moria.de>
29 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
30 .\" Modified 1995-05-18 by Todd Larason <jtl@molehill.org>
31 .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
32 .\" Modified 1995-01-09 by Richard Kettlewell <richard@greenend.org.uk>
33 .\" Modified 1998-05-13 by Michael Haardt <michael@cantor.informatik.rwth-aachen.de>
34 .\" Modified 1999-07-06 by aeb & Albert Cahalan
35 .\" Modified 2000-01-07 by aeb
36 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
37 .\" 2007-06-08 mtk: Added example program
38 .\" 2007-07-05 mtk: Added details on underlying system call interfaces
40 .TH STAT 2 2015-07-23 "Linux" "Linux Programmer's Manual"
42 stat, fstat, lstat, fstatat \- get file status
45 .B #include <sys/types.h>
47 .B #include <sys/stat.h>
49 .B #include <unistd.h>
51 .BI "int stat(const char *" pathname ", struct stat *" buf );
53 .BI "int fstat(int " fd ", struct stat *" buf );
55 .BI "int lstat(const char *" pathname ", struct stat *" buf );
57 .BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
58 .B #include <sys/stat.h>
60 .BI "int fstatat(int " dirfd ", const char *" pathname ", struct stat *" \
66 Feature Test Macro Requirements for glibc (see
67 .BR feature_test_macros (7)):
74 /* glibc 2.19 and earlier */ _BSD_SOURCE
76 || /* Since glibc 2.20 */ _DEFAULT_SOURCE
78 || _XOPEN_SOURCE\ >=\ 500
79 .\" _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
81 || /* Since glibc 2.10: */ _POSIX_C_SOURCE\ >=\ 200112L
90 _POSIX_C_SOURCE\ >=\ 200809L
99 These functions return information about a file, in the buffer pointed to by
101 No permissions are required on the file itself, but\(emin the case of
105 .BR lstat ()\(emexecute
106 (search) permission is required on all of the directories in
108 that lead to the file.
113 retrieve information about the file pointed to by
124 is a symbolic link, then it returns information about the link itself,
125 not the file that it refers to.
130 except that the file about which information is to be retrieved
131 is specified by the file descriptor
134 All of these system calls return a
136 structure, which contains the following fields:
141 dev_t st_dev; /* ID of device containing file */
142 ino_t st_ino; /* inode number */
143 mode_t st_mode; /* file type and mode */
144 nlink_t st_nlink; /* number of hard links */
145 uid_t st_uid; /* user ID of owner */
146 gid_t st_gid; /* group ID of owner */
147 dev_t st_rdev; /* device ID (if special file) */
148 off_t st_size; /* total size, in bytes */
149 blksize_t st_blksize; /* blocksize for filesystem I/O */
150 blkcnt_t st_blocks; /* number of 512B blocks allocated */
152 /* Since Linux 2.6, the kernel supports nanosecond
153 precision for the following timestamp fields.
154 For the details before Linux 2.6, see NOTES. */
156 struct timespec st_atim; /* time of last access */
157 struct timespec st_mtim; /* time of last modification */
158 struct timespec st_ctim; /* time of last status change */
160 #define st_atime st_atim.tv_sec /* Backward compatibility */
161 #define st_mtime st_mtim.tv_sec
162 #define st_ctime st_ctim.tv_sec
168 the order of fields in the
170 structure varies somewhat
171 across architectures.
173 the definition above does not show the padding bytes
174 that may be present between some fields on various architectures.
175 Consult the glibc and kernel source code
176 if you need to know the details.
178 .\" Background: inode attributes are modified with i_mutex held, but
179 .\" read by stat() without taking the mutex.
181 For performance and simplicity reasons, different fields in the
183 structure may contain state information from different moments
184 during the execution of the system call.
189 is changed by another process by calling
196 together with the new
200 together with the new
205 field describes the device on which this file resides.
210 macros may be useful to decompose the device ID in this field.)
214 field describes the device that this file (inode) represents.
218 field gives the size of the file (if it is a regular
219 file or a symbolic link) in bytes.
220 The size of a symbolic link is the length of the pathname
221 it contains, without a terminating null byte.
225 field indicates the number of blocks allocated to the file, 512-byte units.
226 (This may be smaller than
228 when the file has holes.)
232 field gives the "preferred" blocksize for efficient filesystem I/O.
233 (Writing to a file in smaller chunks may cause
234 an inefficient read-modify-rewrite.)
236 Not all of the Linux filesystems implement all of the time fields.
237 Some filesystem types allow mounting in such a way that file
238 and/or directory accesses do not cause an update of the
248 and related information in
252 is not updated if a file is opened with the
259 is changed by file accesses, for example, by
266 (of more than zero bytes).
269 may or may not update
274 is changed by file modifications, for example, by
280 (of more than zero bytes).
283 of a directory is changed by the creation or deletion of files
289 changed for changes in owner, group, hard link count, or mode.
293 is changed by writing or by setting inode information
294 (i.e., owner, group, link count, mode, etc.).
298 bits corresponding to the mask
302 the 12 bits corresponding to the mask 07777 as the
304 and the least significant 9 bits (0777) as the
305 .IR "file permission bits" .
307 The following mask values are defined for the file type of the
313 S_IFMT 0170000 bit mask for the file type bit field
315 S_IFSOCK 0140000 socket
316 S_IFLNK 0120000 symbolic link
317 S_IFREG 0100000 regular file
318 S_IFBLK 0060000 block device
319 S_IFDIR 0040000 directory
320 S_IFCHR 0020000 character device
325 Thus, to test for a regular file (for example), one could write:
330 if ((sb.st_mode & S_IFMT) == S_IFREG) {
331 /* Handle regular file */
336 Because tests of the above form are common, additional
337 macros are defined by POSIX to allow the test of the file type in
339 to be written more concisely:
343 is it a regular file?
358 symbolic link? (Not in POSIX.1-1996.)
361 socket? (Not in POSIX.1-1996.)
364 The preceding code snippet could thus be rewritten as:
369 if (S_ISREG(sb.st_mode)) {
370 /* Handle regular file */
375 The definitions of most of the above file type test macros
376 are provided if any of the following feature test macros is defined:
378 (in glibc 2.19 and earlier),
380 (in glibc 2.19 and earlier),
383 (in glibc 2.20 and later).
384 In addition, definitions of all of the above macros except
393 can also be exposed by defining
395 with a value of 500 or greater.
399 is exposed if any of the following feature test macros is defined:
401 (in glibc 2.19 and earlier),
403 (in glibc 2.20 and later),
405 with a value of 500 or greater, or
407 with a value of 200112L or greater.
409 The following mask values are defined for
410 the file mode component of the
416 S_ISUID 04000 set-user-ID bit
417 S_ISGID 02000 set-group-ID bit (see below)
418 S_ISVTX 01000 sticky bit (see below)
420 S_IRWXU 00700 owner has read, write, and execute permission
421 S_IRUSR 00400 owner has read permission
422 S_IWUSR 00200 owner has write permission
423 S_IXUSR 00100 owner has execute permission
425 S_IRWXG 00070 group has read, write, and execute permission
426 S_IRGRP 00040 group has read permission
427 S_IWGRP 00020 group has write permission
428 S_IXGRP 00010 group has execute permission
431 others (not in group) have read, write, and execute permission
433 S_IROTH 00004 others have read permission
434 S_IWOTH 00002 others have write permission
435 S_IXOTH 00001 others have execute permission
441 has several special uses.
442 For a directory, it indicates that BSD semantics is to be used
443 for that directory: files created there inherit their group ID from
444 the directory, not from the effective group ID of the creating process,
445 and directories created there will also get the
448 For a file that does not have the group execution bit
451 the set-group-ID bit indicates mandatory file/record locking.
455 on a directory means that a file
456 in that directory can be renamed or deleted only by the owner
457 of the file, by the owner of the directory, and by a privileged
464 system call operates in exactly the same way as
466 except for the differences described here.
468 If the pathname given in
470 is relative, then it is interpreted relative to the directory
471 referred to by the file descriptor
473 (rather than relative to the current working directory of
474 the calling process, as is done by
476 for a relative pathname).
486 is interpreted relative to the current working
487 directory of the calling process (like
497 can either be 0, or include one or more of the following flags ORed:
499 .BR AT_EMPTY_PATH " (since Linux 2.6.39)"
500 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
503 is an empty string, operate on the file referred to by
505 (which may have been obtained using the
513 the call operates on the current working directory.
516 can refer to any type of file, not just a directory.
517 This flag is Linux-specific; define
519 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
520 to obtain its definition.
522 .BR AT_NO_AUTOMOUNT " (since Linux 2.6.38)"
523 Don't automount the terminal ("basename") component of
525 if it is a directory that is an automount point.
526 This allows the caller to gather attributes of an automount point
527 (rather than the location it would mount).
528 This flag can be used in tools that scan directories
529 to prevent mass-automounting of a directory of automount points.
532 flag has no effect if the mount point has already been mounted over.
533 This flag is Linux-specific; define
535 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
536 to obtain its definition.
538 .B AT_SYMLINK_NOFOLLOW
541 is a symbolic link, do not dereference it:
542 instead return information about the link itself, like
546 dereferences symbolic links, like
551 for an explanation of the need for
554 On success, zero is returned.
555 On error, \-1 is returned, and
557 is set appropriately.
561 Search permission is denied for one of the directories
562 in the path prefix of
565 .BR path_resolution (7).)
569 is not a valid open file descriptor.
575 Too many symbolic links encountered while traversing the path.
589 Out of memory (i.e., kernel memory).
592 A component of the path prefix of
600 refers to a file whose size, inode number,
601 or number of blocks cannot be represented in, respectively, the types
606 This error can occur when, for example,
607 an application compiled on a 32-bit platform without
608 .I -D_FILE_OFFSET_BITS=64
611 on a file whose size exceeds
615 The following additional errors can occur for
620 is not a valid file descriptor.
623 Invalid flag specified in
630 is a file descriptor referring to a file other than a directory.
633 was added to Linux in kernel 2.6.16;
634 library support was added to glibc in version 2.4.
639 SVr4, 4.3BSD, POSIX.1-2001, POSIX.1.2008.
640 .\" SVr4 documents additional
642 .\" error conditions EINTR, ENOLINK, and EOVERFLOW. SVr4
643 .\" documents additional
647 .\" error conditions EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW.
652 According to POSIX.1-2001,
654 on a symbolic link need return valid information only in the
656 field and the file type of the
661 POSIX.1-2008 tightens the specification, requiring
663 to return valid information in all fields except the mode bits in
670 fields may be less portable.
671 (They were introduced in BSD.
672 The interpretation differs between systems,
673 and possibly on a single system when NFS mounts are involved.)
674 If you need to obtain the definition of the
682 with the value 500 or greater (before including
686 POSIX.1-1990 did not describe the
696 constants, but instead demanded the use of
702 constants are present in POSIX.1-2001 and later.
709 POSIX.1-1996, but both are present in POSIX.1-2001;
710 the former is from SVID 4, the latter from SUSv2.
712 UNIX\ V7 (and later systems) had
717 prescribes the synonyms
722 Values that have been (or are) in use on various systems:
726 hex name ls octal description
727 f000 S_IFMT 170000 mask for file type
729 SCO out-of-service inode; BSD unknown type; SVID-v2 and XPG2
730 have both 0 and 0100000 for ordinary file
732 1000 S_IFIFO p| 010000 FIFO (named pipe)
733 2000 S_IFCHR c 020000 character special (V7)
734 3000 S_IFMPC 030000 multiplexed character special (V7)
735 4000 S_IFDIR d/ 040000 directory (V7)
736 5000 S_IFNAM 050000 T{
737 XENIX named special file with two subtypes, distinguished by
738 \fIst_rdev\fP values 1, 2
740 0001 S_INSEM s 000001 XENIX semaphore subtype of IFNAM
741 0002 S_INSHD m 000002 XENIX shared data subtype of IFNAM
742 6000 S_IFBLK b 060000 block special (V7)
743 7000 S_IFMPB 070000 multiplexed block special (V7)
744 8000 S_IFREG - 100000 regular (V7)
745 9000 S_IFCMP 110000 VxFS compressed
746 9000 S_IFNWK n 110000 network special (HP-UX)
747 a000 S_IFLNK l@ 120000 symbolic link (BSD)
748 b000 S_IFSHAD 130000 T{
749 Solaris shadow inode for ACL (not seen by user space)
751 c000 S_IFSOCK s= 140000 socket (BSD; also "S_IFSOC" on VxFS)
752 d000 S_IFDOOR D> 150000 Solaris door
753 e000 S_IFWHT w% 160000 BSD whiteout (not used for inode)
754 0200 S_ISVTX 001000 T{
755 sticky bit: save swapped text even after use (V7)
759 On nondirectories: don't cache this file (SunOS)
761 On directories: restricted deletion flag (SVID-v4.2)
763 0400 S_ISGID 002000 T{
764 set-group-ID on execution (V7)
766 for directories: use BSD semantics for propagation of GID
768 0400 S_ENFMT 002000 T{
769 System V file locking enforcement (shared with S_ISGID)
771 0800 S_ISUID 004000 set-user-ID on execution (V7)
773 directory is a context dependent file (HP-UX)
778 A sticky command appeared in Version 32V AT&T UNIX.
782 will generally not trigger automounter action, whereas
787 For most files under the
791 does not return the file size in the
793 field; instead the field is returned with the value 0.
795 Older kernels and older standards did not support nanosecond timestamp
797 Instead, there were three timestamp
798 .RI fields\(em st_atime ,
801 .IR st_ctime \(emtyped
804 that recorded timestamps with one-second precision.
806 Since kernel 2.5.48, the
808 structure supports nanosecond resolution for the three file timestamp fields.
809 The nanosecond components of each timestamp are available
810 via names of the form
816 feature test macro is defined.
817 Nanosecond timestamps are nowadays standardized,
818 starting with POSIX.1-2008, and, starting with version 2.12,
819 glibc also exposes the nanosecond component names if
821 is defined with the value 200809L or greater, or
823 is defined with the value 700 or greater.
824 If none of the aforementioned macros are defined,
825 then the nanosecond values are exposed with names of the form
828 Nanosecond timestamps are supported on XFS, JFS, Btrfs, and
829 ext4 (since Linux 2.6.23).
830 .\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80
831 Nanosecond timestamps are not supported in ext2, ext3, and Reiserfs.
832 On filesystems that do not support subsecond timestamps,
833 the nanosecond fields are returned with the value 0.
834 .SS C library/kernel differences
835 Over time, increases in the size of the
837 structure have led to three successive versions of
849 on 32-bit platforms such as i386.
850 The first two versions were already present in Linux 1.0
851 (albeit with different names);
852 .\" See include/asm-i386/stat.h in the Linux 2.4 source code for the
853 .\" various versions of the structure definitions
854 the last was added in Linux 2.4.
855 Similar remarks apply for
860 The kernel-internal versions of the
862 structure dealt with by the different versions are, respectively:
865 .IR __old_kernel_stat
866 The original structure, with rather narrow fields, and no padding.
871 field and padding added to various parts of the structure to
872 allow for future expansion.
882 fields to accommodate the Linux-2.4 expansion of UIDs and GIDs to 32 bits,
883 and various other enlarged fields and further padding in the structure.
884 (Various padding bytes were eventually consumed in Linux 2.6,
885 with the advent of 32-bit device IDs and nanosecond components
886 for the timestamp fields.)
891 wrapper function hides these details from applications,
892 invoking the most recent version of the system call provided by the kernel,
893 and repacking the returned information if required for old binaries.
895 .\" A note from Andries Brouwer, July 2007
897 .\" > Is the story not rather more complicated for some calls like
900 .\" Yes and no, mostly no. See /usr/include/sys/stat.h .
902 .\" The idea is here not so much that syscalls change, but that
903 .\" the definitions of struct stat and of the types dev_t and mode_t change.
904 .\" This means that libc (even if it does not call the kernel
905 .\" but only calls some internal function) must know what the
906 .\" format of dev_t or of struct stat is.
907 .\" The communication between the application and libc goes via
908 .\" the include file <sys/stat.h> that defines a _STAT_VER and
909 .\" _MKNOD_VER describing the layout of the data that user space
910 .\" uses. Each (almost each) occurrence of stat() is replaced by
911 .\" an occurrence of xstat() where the first parameter of xstat()
912 .\" is this version number _STAT_VER.
914 .\" Now, also the definitions used by the kernel change.
915 .\" But glibc copes with this in the standard way, and the
916 .\" struct stat as returned by the kernel is repacked into
917 .\" the struct stat as expected by the application.
918 .\" Thus, _STAT_VER and this setup cater for the application-libc
919 .\" interface, rather than the libc-kernel interface.
921 .\" (Note that the details depend on gcc being used as c compiler.)
923 On modern 64-bit systems, life is simpler: there is a single
925 system call and the kernel deals with a
927 structure that contains fields of a sufficient size.
929 The underlying system call employed by the glibc
931 wrapper function is actually called
933 or, on some architectures,
934 .\" strace(1) shows the name "newfstatat" on x86-64
937 The following program calls
939 and displays selected fields in the returned
944 #include <sys/types.h>
945 #include <sys/stat.h>
951 main(int argc, char *argv[])
956 fprintf(stderr, "Usage: %s <pathname>\\n", argv[0]);
960 if (stat(argv[1], &sb) == \-1) {
965 printf("File type: ");
967 switch (sb.st_mode & S_IFMT) {
968 case S_IFBLK: printf("block device\\n"); break;
969 case S_IFCHR: printf("character device\\n"); break;
970 case S_IFDIR: printf("directory\\n"); break;
971 case S_IFIFO: printf("FIFO/pipe\\n"); break;
972 case S_IFLNK: printf("symlink\\n"); break;
973 case S_IFREG: printf("regular file\\n"); break;
974 case S_IFSOCK: printf("socket\\n"); break;
975 default: printf("unknown?\\n"); break;
978 printf("I\-node number: %ld\\n", (long) sb.st_ino);
980 printf("Mode: %lo (octal)\\n",
981 (unsigned long) sb.st_mode);
983 printf("Link count: %ld\\n", (long) sb.st_nlink);
984 printf("Ownership: UID=%ld GID=%ld\\n",
985 (long) sb.st_uid, (long) sb.st_gid);
987 printf("Preferred I/O block size: %ld bytes\\n",
988 (long) sb.st_blksize);
989 printf("File size: %lld bytes\\n",
990 (long long) sb.st_size);
991 printf("Blocks allocated: %lld\\n",
992 (long long) sb.st_blocks);
994 printf("Last status change: %s", ctime(&sb.st_ctime));
995 printf("Last file access: %s", ctime(&sb.st_atime));
996 printf("Last file modification: %s", ctime(&sb.st_mtime));
1009 .BR capabilities (7),