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-03-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 _BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
75 _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
77 || /* Since glibc 2.10: */ _POSIX_C_SOURCE\ >=\ 200112L
86 _XOPEN_SOURCE\ >=\ 700 || _POSIX_C_SOURCE\ >=\ 200809L
95 These functions return information about a file, in the buffer pointed to by
97 No permissions are required on the file itself, but\(emin the case of
101 .BR lstat ()\(emexecute
102 (search) permission is required on all of the directories in
104 that lead to the file.
109 retrieve information about the file pointed to by
120 is a symbolic link, then it returns information about the link itself,
121 not the file that it refers to.
126 except that the file about which information is to be retrieved
127 is specified by the file descriptor
130 All of these system calls return a
132 structure, which contains the following fields:
137 dev_t st_dev; /* ID of device containing file */
138 ino_t st_ino; /* inode number */
139 mode_t st_mode; /* protection */
140 nlink_t st_nlink; /* number of hard links */
141 uid_t st_uid; /* user ID of owner */
142 gid_t st_gid; /* group ID of owner */
143 dev_t st_rdev; /* device ID (if special file) */
144 off_t st_size; /* total size, in bytes */
145 blksize_t st_blksize; /* blocksize for filesystem I/O */
146 blkcnt_t st_blocks; /* number of 512B blocks allocated */
148 /* Since Linux 2.6, the kernel supports nanosecond
149 precision for the following timestamp fields.
150 For the details before Linux 2.6, see NOTES. */
152 struct timespec st_atim; /* time of last access */
153 struct timespec st_mtim; /* time of last modification */
154 struct timespec st_ctim; /* time of last status change */
156 #define st_atime st_atim.tv_sec /* Backward compatibility */
157 #define st_mtime st_mtim.tv_sec
158 #define st_ctime st_ctim.tv_sec
164 the order of fields in the
166 structure varies somewhat
167 across architectures.
169 the definition above does not show the padding bytes
170 that may be present between some fields on various architectures.
171 Consult the the glibc and kernel source code
172 if you need to know the details.
176 field describes the device on which this file resides.
181 macros may be useful to decompose the device ID in this field.)
185 field describes the device that this file (inode) represents.
189 field gives the size of the file (if it is a regular
190 file or a symbolic link) in bytes.
191 The size of a symbolic link is the length of the pathname
192 it contains, without a terminating null byte.
196 field indicates the number of blocks allocated to the file, 512-byte units.
197 (This may be smaller than
199 when the file has holes.)
203 field gives the "preferred" blocksize for efficient filesystem I/O.
204 (Writing to a file in smaller chunks may cause
205 an inefficient read-modify-rewrite.)
207 Not all of the Linux filesystems implement all of the time fields.
208 Some filesystem types allow mounting in such a way that file
209 and/or directory accesses do not cause an update of the
219 and related information in
223 is not updated if a file is opened with the
230 is changed by file accesses, for example, by
237 (of more than zero bytes).
240 may or may not update
245 is changed by file modifications, for example, by
251 (of more than zero bytes).
254 of a directory is changed by the creation or deletion of files
260 changed for changes in owner, group, hard link count, or mode.
264 is changed by writing or by setting inode information
265 (i.e., owner, group, link count, mode, etc.).
267 The following POSIX macros are defined to check the file type using the
273 is it a regular file?
288 symbolic link? (Not in POSIX.1-1996.)
291 socket? (Not in POSIX.1-1996.)
294 The following flags are defined for the
300 S_IFMT 0170000 bit mask for the file type bit fields
301 S_IFSOCK 0140000 socket
302 S_IFLNK 0120000 symbolic link
303 S_IFREG 0100000 regular file
304 S_IFBLK 0060000 block device
305 S_IFDIR 0040000 directory
306 S_IFCHR 0020000 character device
308 S_ISUID 0004000 set-user-ID bit
309 S_ISGID 0002000 set-group-ID bit (see below)
310 S_ISVTX 0001000 sticky bit (see below)
311 S_IRWXU 00700 mask for file owner permissions
312 S_IRUSR 00400 owner has read permission
313 S_IWUSR 00200 owner has write permission
314 S_IXUSR 00100 owner has execute permission
315 S_IRWXG 00070 mask for group permissions
316 S_IRGRP 00040 group has read permission
317 S_IWGRP 00020 group has write permission
318 S_IXGRP 00010 group has execute permission
320 mask for permissions for others (not in group)
322 S_IROTH 00004 others have read permission
323 S_IWOTH 00002 others have write permission
324 S_IXOTH 00001 others have execute permission
330 has several special uses.
331 For a directory it indicates that BSD semantics is to be used
332 for that directory: files created there inherit their group ID from
333 the directory, not from the effective group ID of the creating process,
334 and directories created there will also get the
337 For a file that does not have the group execution bit
340 the set-group-ID bit indicates mandatory file/record locking.
344 on a directory means that a file
345 in that directory can be renamed or deleted only by the owner
346 of the file, by the owner of the directory, and by a privileged
353 system call operates in exactly the same way as
355 except for the differences described here.
357 If the pathname given in
359 is relative, then it is interpreted relative to the directory
360 referred to by the file descriptor
362 (rather than relative to the current working directory of
363 the calling process, as is done by
365 for a relative pathname).
375 is interpreted relative to the current working
376 directory of the calling process (like
386 can either be 0, or include one or more of the following flags ORed:
388 .BR AT_EMPTY_PATH " (since Linux 2.6.39)"
389 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
392 is an empty string, operate on the file referred to by
394 (which may have been obtained using the
402 the call operates on the current working directory.
405 can refer to any type of file, not just a directory.
406 This flag is Linux-specific; define
408 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
409 to obtain its definition.
411 .BR AT_NO_AUTOMOUNT " (since Linux 2.6.38)"
412 Don't automount the terminal ("basename") component of
414 if it is a directory that is an automount point.
415 This allows the caller to gather attributes of an automount point
416 (rather than the location it would mount).
417 This flag can be used in tools that scan directories
418 to prevent mass-automounting of a directory of automount points.
421 flag has no effect if the mount point has already been mounted over.
422 This flag is Linux-specific; define
424 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
425 to obtain its definition.
427 .B AT_SYMLINK_NOFOLLOW
430 is a symbolic link, do not dereference it:
431 instead return information about the link itself, like
435 dereferences symbolic links, like
440 for an explanation of the need for
443 On success, zero is returned.
444 On error, \-1 is returned, and
446 is set appropriately.
450 Search permission is denied for one of the directories
451 in the path prefix of
454 .BR path_resolution (7).)
464 Too many symbolic links encountered while traversing the path.
478 Out of memory (i.e., kernel memory).
481 A component of the path prefix of
489 refers to a file whose size, inode number,
490 or number of blocks cannot be represented in, respectively, the types
495 This error can occur when, for example,
496 an application compiled on a 32-bit platform without
497 .I -D_FILE_OFFSET_BITS=64
500 on a file whose size exceeds
504 The following additional errors can occur for
509 is not a valid file descriptor.
512 Invalid flag specified in
519 is a file descriptor referring to a file other than a directory.
522 was added to Linux in kernel 2.6.16;
523 library support was added to glibc in version 2.4.
528 SVr4, 4.3BSD, POSIX.1-2001, POSIX.1.2008.
529 .\" SVr4 documents additional
531 .\" error conditions EINTR, ENOLINK, and EOVERFLOW. SVr4
532 .\" documents additional
536 .\" error conditions EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW.
541 According to POSIX.1-2001,
543 on a symbolic link need return valid information only in the
545 field and the file-type component of the
550 POSIX.1-2008 tightens the specification, requiring
552 to return valid information in all fields except the permission bits in
559 fields may be less portable.
560 (They were introduced in BSD.
561 The interpretation differs between systems,
562 and possibly on a single system when NFS mounts are involved.)
563 If you need to obtain the definition of the
571 with the value 500 or greater (before including
575 POSIX.1-1990 did not describe the
585 constants, but instead demanded the use of
591 constants are present in POSIX.1-2001 and later.
598 POSIX.1-1996, but both are present in POSIX.1-2001;
599 the former is from SVID 4, the latter from SUSv2.
601 UNIX V7 (and later systems) had
606 prescribes the synonyms
611 Values that have been (or are) in use on various systems:
615 hex name ls octal description
616 f000 S_IFMT 170000 mask for file type
618 SCO out-of-service inode; BSD unknown type; SVID-v2 and XPG2
619 have both 0 and 0100000 for ordinary file
621 1000 S_IFIFO p| 010000 FIFO (named pipe)
622 2000 S_IFCHR c 020000 character special (V7)
623 3000 S_IFMPC 030000 multiplexed character special (V7)
624 4000 S_IFDIR d/ 040000 directory (V7)
625 5000 S_IFNAM 050000 T{
626 XENIX named special file with two subtypes, distinguished by
627 \fIst_rdev\fP values 1, 2
629 0001 S_INSEM s 000001 XENIX semaphore subtype of IFNAM
630 0002 S_INSHD m 000002 XENIX shared data subtype of IFNAM
631 6000 S_IFBLK b 060000 block special (V7)
632 7000 S_IFMPB 070000 multiplexed block special (V7)
633 8000 S_IFREG - 100000 regular (V7)
634 9000 S_IFCMP 110000 VxFS compressed
635 9000 S_IFNWK n 110000 network special (HP-UX)
636 a000 S_IFLNK l@ 120000 symbolic link (BSD)
637 b000 S_IFSHAD 130000 T{
638 Solaris shadow inode for ACL (not seen by user space)
640 c000 S_IFSOCK s= 140000 socket (BSD; also "S_IFSOC" on VxFS)
641 d000 S_IFDOOR D> 150000 Solaris door
642 e000 S_IFWHT w% 160000 BSD whiteout (not used for inode)
643 0200 S_ISVTX 001000 T{
644 sticky bit: save swapped text even after use (V7)
648 On nondirectories: don't cache this file (SunOS)
650 On directories: restricted deletion flag (SVID-v4.2)
652 0400 S_ISGID 002000 T{
653 set-group-ID on execution (V7)
655 for directories: use BSD semantics for propagation of GID
657 0400 S_ENFMT 002000 T{
658 System V file locking enforcement (shared with S_ISGID)
660 0800 S_ISUID 004000 set-user-ID on execution (V7)
662 directory is a context dependent file (HP-UX)
667 A sticky command appeared in Version 32V AT&T UNIX.
671 will generally not trigger automounter action, whereas
676 For most files under the
680 does not return the file size in the
682 field; instead the field is returned with the value 0.
684 Older kernels and older standards did not support nanosecond timestamp
686 Instead, there were three timestamp
687 .RI fields\(em st_atime ,
690 .IR st_ctime \(emtyped
693 that recorded timestamps with one-second precision.
695 Since kernel 2.5.48, the
697 structure supports nanosecond resolution for the three file timestamp fields.
698 The nanosecond components of each timestamp are available
699 via names of the form
705 feature test macro is defined.
706 Nanosecond timestamps are nowadays standardized,
707 starting with POSIX.1-2008, and, starting with version 2.12,
708 glibc also exposes the nanosecond component names if
710 is defined with the value 200809L or greater, or
712 is defined with the value 700 or greater.
713 If none of the aforementioned macros are defined,
714 then the nanosecond values are exposed with names of the form
717 Nanosecond timestamps are supported on XFS, JFS, Btrfs, and
718 ext4 (since Linux 2.6.23).
719 .\" commit ef7f38359ea8b3e9c7f2cae9a4d4935f55ca9e80
720 Nanosecond timestamps are not supported in ext2, ext3, and Resierfs.
721 On filesystems that do not support subsecond timestamps,
722 the nanosecond fields are returned with the value 0.
723 .SS Underlying kernel interface
724 Over time, increases in the size of the
726 structure have led to three successive versions of
736 (new in kernel 2.4; slot
740 wrapper function hides these details from applications,
741 invoking the most recent version of the system call provided by the kernel,
742 and repacking the returned information if required for old binaries.
743 Similar remarks apply for
748 .\" A note from Andries Brouwer, July 2007
750 .\" > Is the story not rather more complicated for some calls like
753 .\" Yes and no, mostly no. See /usr/include/sys/stat.h .
755 .\" The idea is here not so much that syscalls change, but that
756 .\" the definitions of struct stat and of the types dev_t and mode_t change.
757 .\" This means that libc (even if it does not call the kernel
758 .\" but only calls some internal function) must know what the
759 .\" format of dev_t or of struct stat is.
760 .\" The communication between the application and libc goes via
761 .\" the include file <sys/stat.h> that defines a _STAT_VER and
762 .\" _MKNOD_VER describing the layout of the data that user space
763 .\" uses. Each (almost each) occurrence of stat() is replaced by
764 .\" an occurrence of xstat() where the first parameter of xstat()
765 .\" is this version number _STAT_VER.
767 .\" Now, also the definitions used by the kernel change.
768 .\" But glibc copes with this in the standard way, and the
769 .\" struct stat as returned by the kernel is repacked into
770 .\" the struct stat as expected by the application.
771 .\" Thus, _STAT_VER and this setup cater for the application-libc
772 .\" interface, rather than the libc-kernel interface.
774 .\" (Note that the details depend on gcc being used as c compiler.)
776 The underlying system call employed by the glibc
778 wrapper function is actually called
781 The following program calls
783 and displays selected fields in the returned
788 #include <sys/types.h>
789 #include <sys/stat.h>
795 main(int argc, char *argv[])
800 fprintf(stderr, "Usage: %s <pathname>\\n", argv[0]);
804 if (stat(argv[1], &sb) == \-1) {
809 printf("File type: ");
811 switch (sb.st_mode & S_IFMT) {
812 case S_IFBLK: printf("block device\\n"); break;
813 case S_IFCHR: printf("character device\\n"); break;
814 case S_IFDIR: printf("directory\\n"); break;
815 case S_IFIFO: printf("FIFO/pipe\\n"); break;
816 case S_IFLNK: printf("symlink\\n"); break;
817 case S_IFREG: printf("regular file\\n"); break;
818 case S_IFSOCK: printf("socket\\n"); break;
819 default: printf("unknown?\\n"); break;
822 printf("I\-node number: %ld\\n", (long) sb.st_ino);
824 printf("Mode: %lo (octal)\\n",
825 (unsigned long) sb.st_mode);
827 printf("Link count: %ld\\n", (long) sb.st_nlink);
828 printf("Ownership: UID=%ld GID=%ld\\n",
829 (long) sb.st_uid, (long) sb.st_gid);
831 printf("Preferred I/O block size: %ld bytes\\n",
832 (long) sb.st_blksize);
833 printf("File size: %lld bytes\\n",
834 (long long) sb.st_size);
835 printf("Blocks allocated: %lld\\n",
836 (long long) sb.st_blocks);
838 printf("Last status change: %s", ctime(&sb.st_ctime));
839 printf("Last file access: %s", ctime(&sb.st_atime));
840 printf("Last file modification: %s", ctime(&sb.st_mtime));
853 .BR capabilities (7),
856 This page is part of release 3.65 of the Linux
859 A description of the project,
860 and information about reporting bugs,
862 \%http://www.kernel.org/doc/man\-pages/.