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 2014-08-19 "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 _XOPEN_SOURCE\ >=\ 700 || _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; /* protection */
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 the glibc and kernel source code
176 if you need to know the details.
180 field describes the device on which this file resides.
185 macros may be useful to decompose the device ID in this field.)
189 field describes the device that this file (inode) represents.
193 field gives the size of the file (if it is a regular
194 file or a symbolic link) in bytes.
195 The size of a symbolic link is the length of the pathname
196 it contains, without a terminating null byte.
200 field indicates the number of blocks allocated to the file, 512-byte units.
201 (This may be smaller than
203 when the file has holes.)
207 field gives the "preferred" blocksize for efficient filesystem I/O.
208 (Writing to a file in smaller chunks may cause
209 an inefficient read-modify-rewrite.)
211 Not all of the Linux filesystems implement all of the time fields.
212 Some filesystem types allow mounting in such a way that file
213 and/or directory accesses do not cause an update of the
223 and related information in
227 is not updated if a file is opened with the
234 is changed by file accesses, for example, by
241 (of more than zero bytes).
244 may or may not update
249 is changed by file modifications, for example, by
255 (of more than zero bytes).
258 of a directory is changed by the creation or deletion of files
264 changed for changes in owner, group, hard link count, or mode.
268 is changed by writing or by setting inode information
269 (i.e., owner, group, link count, mode, etc.).
271 The following mask values are defined for the file type component of the
277 S_IFMT 0170000 bit mask for the file type bit fields
279 S_IFSOCK 0140000 socket
280 S_IFLNK 0120000 symbolic link
281 S_IFREG 0100000 regular file
282 S_IFBLK 0060000 block device
283 S_IFDIR 0040000 directory
284 S_IFCHR 0020000 character device
289 Thus, to test for a regular file (for example), one could write:
294 if ((sb.st_mode & S_IFMT) == S_IFREG) {
295 /* Handle regular file */
300 Because tests of the above form are common, additional
301 macros are defined by POSIX to allow the test of the file type in
303 to be written more concisely:
307 is it a regular file?
322 symbolic link? (Not in POSIX.1-1996.)
325 socket? (Not in POSIX.1-1996.)
328 The preceding code snippet could thus be rewritten as:
333 if (S_ISREG(sb.st_mode)) {
334 /* Handle regular file */
339 The definitions of most of the above file type test macros
340 are provided if any of the following feature test macros is defined:
342 (in glibc 2.19 and earlier),
344 (in glibc 2.19 and earlier),
347 (in glibc 2.20 and later).
348 In addition, definitions of all of the above macros except
357 can also be exposed by defining
359 with a value of 500 or greater.
363 is exposed if any of the following feature test macros is defined:
365 (in glibc 2.19 and earlier),
367 (in glibc 2.20 and later),
369 with a value of 500 or greater, or
371 with a value of 200112L or greater.
373 The following mask values are defined for
374 the file permissions component of the
380 S_ISUID 0004000 set-user-ID bit
381 S_ISGID 0002000 set-group-ID bit (see below)
382 S_ISVTX 0001000 sticky bit (see below)
384 S_IRWXU 00700 mask for file owner permissions
385 S_IRUSR 00400 owner has read permission
386 S_IWUSR 00200 owner has write permission
387 S_IXUSR 00100 owner has execute permission
389 S_IRWXG 00070 mask for group permissions
390 S_IRGRP 00040 group has read permission
391 S_IWGRP 00020 group has write permission
392 S_IXGRP 00010 group has execute permission
395 mask for permissions for others (not in group)
397 S_IROTH 00004 others have read permission
398 S_IWOTH 00002 others have write permission
399 S_IXOTH 00001 others have execute permission
405 has several special uses.
406 For a directory, it indicates that BSD semantics is to be used
407 for that directory: files created there inherit their group ID from
408 the directory, not from the effective group ID of the creating process,
409 and directories created there will also get the
412 For a file that does not have the group execution bit
415 the set-group-ID bit indicates mandatory file/record locking.
419 on a directory means that a file
420 in that directory can be renamed or deleted only by the owner
421 of the file, by the owner of the directory, and by a privileged
428 system call operates in exactly the same way as
430 except for the differences described here.
432 If the pathname given in
434 is relative, then it is interpreted relative to the directory
435 referred to by the file descriptor
437 (rather than relative to the current working directory of
438 the calling process, as is done by
440 for a relative pathname).
450 is interpreted relative to the current working
451 directory of the calling process (like
461 can either be 0, or include one or more of the following flags ORed:
463 .BR AT_EMPTY_PATH " (since Linux 2.6.39)"
464 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
467 is an empty string, operate on the file referred to by
469 (which may have been obtained using the
477 the call operates on the current working directory.
480 can refer to any type of file, not just a directory.
481 This flag is Linux-specific; define
483 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
484 to obtain its definition.
486 .BR AT_NO_AUTOMOUNT " (since Linux 2.6.38)"
487 Don't automount the terminal ("basename") component of
489 if it is a directory that is an automount point.
490 This allows the caller to gather attributes of an automount point
491 (rather than the location it would mount).
492 This flag can be used in tools that scan directories
493 to prevent mass-automounting of a directory of automount points.
496 flag has no effect if the mount point has already been mounted over.
497 This flag is Linux-specific; define
499 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
500 to obtain its definition.
502 .B AT_SYMLINK_NOFOLLOW
505 is a symbolic link, do not dereference it:
506 instead return information about the link itself, like
510 dereferences symbolic links, like
515 for an explanation of the need for
518 On success, zero is returned.
519 On error, \-1 is returned, and
521 is set appropriately.
525 Search permission is denied for one of the directories
526 in the path prefix of
529 .BR path_resolution (7).)
539 Too many symbolic links encountered while traversing the path.
553 Out of memory (i.e., kernel memory).
556 A component of the path prefix of
564 refers to a file whose size, inode number,
565 or number of blocks cannot be represented in, respectively, the types
570 This error can occur when, for example,
571 an application compiled on a 32-bit platform without
572 .I -D_FILE_OFFSET_BITS=64
575 on a file whose size exceeds
579 The following additional errors can occur for
584 is not a valid file descriptor.
587 Invalid flag specified in
594 is a file descriptor referring to a file other than a directory.
597 was added to Linux in kernel 2.6.16;
598 library support was added to glibc in version 2.4.
603 SVr4, 4.3BSD, POSIX.1-2001, POSIX.1.2008.
604 .\" SVr4 documents additional
606 .\" error conditions EINTR, ENOLINK, and EOVERFLOW. SVr4
607 .\" documents additional
611 .\" error conditions EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW.
616 According to POSIX.1-2001,
618 on a symbolic link need return valid information only in the
620 field and the file-type component of the
625 POSIX.1-2008 tightens the specification, requiring
627 to return valid information in all fields except the permission bits in
634 fields may be less portable.
635 (They were introduced in BSD.
636 The interpretation differs between systems,
637 and possibly on a single system when NFS mounts are involved.)
638 If you need to obtain the definition of the
646 with the value 500 or greater (before including
650 POSIX.1-1990 did not describe the
660 constants, but instead demanded the use of
666 constants are present in POSIX.1-2001 and later.
673 POSIX.1-1996, but both are present in POSIX.1-2001;
674 the former is from SVID 4, the latter from SUSv2.
676 UNIX\ V7 (and later systems) had
681 prescribes the synonyms
686 Values that have been (or are) in use on various systems:
690 hex name ls octal description
691 f000 S_IFMT 170000 mask for file type
693 SCO out-of-service inode; BSD unknown type; SVID-v2 and XPG2
694 have both 0 and 0100000 for ordinary file
696 1000 S_IFIFO p| 010000 FIFO (named pipe)
697 2000 S_IFCHR c 020000 character special (V7)
698 3000 S_IFMPC 030000 multiplexed character special (V7)
699 4000 S_IFDIR d/ 040000 directory (V7)
700 5000 S_IFNAM 050000 T{
701 XENIX named special file with two subtypes, distinguished by
702 \fIst_rdev\fP values 1, 2
704 0001 S_INSEM s 000001 XENIX semaphore subtype of IFNAM
705 0002 S_INSHD m 000002 XENIX shared data subtype of IFNAM
706 6000 S_IFBLK b 060000 block special (V7)
707 7000 S_IFMPB 070000 multiplexed block special (V7)
708 8000 S_IFREG - 100000 regular (V7)
709 9000 S_IFCMP 110000 VxFS compressed
710 9000 S_IFNWK n 110000 network special (HP-UX)
711 a000 S_IFLNK l@ 120000 symbolic link (BSD)
712 b000 S_IFSHAD 130000 T{
713 Solaris shadow inode for ACL (not seen by user space)
715 c000 S_IFSOCK s= 140000 socket (BSD; also "S_IFSOC" on VxFS)
716 d000 S_IFDOOR D> 150000 Solaris door
717 e000 S_IFWHT w% 160000 BSD whiteout (not used for inode)
718 0200 S_ISVTX 001000 T{
719 sticky bit: save swapped text even after use (V7)
723 On nondirectories: don't cache this file (SunOS)
725 On directories: restricted deletion flag (SVID-v4.2)
727 0400 S_ISGID 002000 T{
728 set-group-ID on execution (V7)
730 for directories: use BSD semantics for propagation of GID
732 0400 S_ENFMT 002000 T{
733 System V file locking enforcement (shared with S_ISGID)
735 0800 S_ISUID 004000 set-user-ID on execution (V7)
737 directory is a context dependent file (HP-UX)
742 A sticky command appeared in Version 32V AT&T UNIX.
746 will generally not trigger automounter action, whereas
751 For most files under the
755 does not return the file size in the
757 field; instead the field is returned with the value 0.
759 Older kernels and older standards did not support nanosecond timestamp
761 Instead, there were three timestamp
762 .RI fields\(em st_atime ,
765 .IR st_ctime \(emtyped
768 that recorded timestamps with one-second precision.
770 Since kernel 2.5.48, the
772 structure supports nanosecond resolution for the three file timestamp fields.
773 The nanosecond components of each timestamp are available
774 via names of the form
780 feature test macro is defined.
781 Nanosecond timestamps are nowadays standardized,
782 starting with POSIX.1-2008, and, starting with version 2.12,
783 glibc also exposes the nanosecond component names if
785 is defined with the value 200809L or greater, or
787 is defined with the value 700 or greater.
788 If none of the aforementioned macros are defined,
789 then the nanosecond values are exposed with names of the form
792 Nanosecond timestamps are supported on XFS, JFS, Btrfs, and
793 ext4 (since Linux 2.6.23).
794 .\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80
795 Nanosecond timestamps are not supported in ext2, ext3, and Reiserfs.
796 On filesystems that do not support subsecond timestamps,
797 the nanosecond fields are returned with the value 0.
798 .SS Underlying kernel interface
799 Over time, increases in the size of the
801 structure have led to three successive versions of
811 (new in kernel 2.4; slot
815 wrapper function hides these details from applications,
816 invoking the most recent version of the system call provided by the kernel,
817 and repacking the returned information if required for old binaries.
818 Similar remarks apply for
823 .\" A note from Andries Brouwer, July 2007
825 .\" > Is the story not rather more complicated for some calls like
828 .\" Yes and no, mostly no. See /usr/include/sys/stat.h .
830 .\" The idea is here not so much that syscalls change, but that
831 .\" the definitions of struct stat and of the types dev_t and mode_t change.
832 .\" This means that libc (even if it does not call the kernel
833 .\" but only calls some internal function) must know what the
834 .\" format of dev_t or of struct stat is.
835 .\" The communication between the application and libc goes via
836 .\" the include file <sys/stat.h> that defines a _STAT_VER and
837 .\" _MKNOD_VER describing the layout of the data that user space
838 .\" uses. Each (almost each) occurrence of stat() is replaced by
839 .\" an occurrence of xstat() where the first parameter of xstat()
840 .\" is this version number _STAT_VER.
842 .\" Now, also the definitions used by the kernel change.
843 .\" But glibc copes with this in the standard way, and the
844 .\" struct stat as returned by the kernel is repacked into
845 .\" the struct stat as expected by the application.
846 .\" Thus, _STAT_VER and this setup cater for the application-libc
847 .\" interface, rather than the libc-kernel interface.
849 .\" (Note that the details depend on gcc being used as c compiler.)
851 The underlying system call employed by the glibc
853 wrapper function is actually called
856 The following program calls
858 and displays selected fields in the returned
863 #include <sys/types.h>
864 #include <sys/stat.h>
870 main(int argc, char *argv[])
875 fprintf(stderr, "Usage: %s <pathname>\\n", argv[0]);
879 if (stat(argv[1], &sb) == \-1) {
884 printf("File type: ");
886 switch (sb.st_mode & S_IFMT) {
887 case S_IFBLK: printf("block device\\n"); break;
888 case S_IFCHR: printf("character device\\n"); break;
889 case S_IFDIR: printf("directory\\n"); break;
890 case S_IFIFO: printf("FIFO/pipe\\n"); break;
891 case S_IFLNK: printf("symlink\\n"); break;
892 case S_IFREG: printf("regular file\\n"); break;
893 case S_IFSOCK: printf("socket\\n"); break;
894 default: printf("unknown?\\n"); break;
897 printf("I\-node number: %ld\\n", (long) sb.st_ino);
899 printf("Mode: %lo (octal)\\n",
900 (unsigned long) sb.st_mode);
902 printf("Link count: %ld\\n", (long) sb.st_nlink);
903 printf("Ownership: UID=%ld GID=%ld\\n",
904 (long) sb.st_uid, (long) sb.st_gid);
906 printf("Preferred I/O block size: %ld bytes\\n",
907 (long) sb.st_blksize);
908 printf("File size: %lld bytes\\n",
909 (long long) sb.st_size);
910 printf("Blocks allocated: %lld\\n",
911 (long long) sb.st_blocks);
913 printf("Last status change: %s", ctime(&sb.st_ctime));
914 printf("Last file access: %s", ctime(&sb.st_atime));
915 printf("Last file modification: %s", ctime(&sb.st_mtime));
928 .BR capabilities (7),