1 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
2 .\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95
3 .\" and Copyright (c) 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
5 .\" %%%LICENSE_START(VERBATIM)
6 .\" Permission is granted to make and distribute verbatim copies of this
7 .\" manual provided the copyright notice and this permission notice are
8 .\" preserved on all copies.
10 .\" Permission is granted to copy and distribute modified versions of this
11 .\" manual under the conditions for verbatim copying, provided that the
12 .\" entire resulting derived work is distributed under the terms of a
13 .\" permission notice identical to this one.
15 .\" Since the Linux kernel and libraries are constantly changing, this
16 .\" manual page may be incorrect or out-of-date. The author(s) assume no
17 .\" responsibility for errors or omissions, or for damages resulting from
18 .\" the use of the information contained herein. The author(s) may not
19 .\" have taken the same level of care in the production of this manual,
20 .\" which is licensed free of charge, as they might when working
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
27 .\" Modified by Michael Haardt <michael@moria.de>
28 .\" Modified 1993-07-24 by Rik Faith <faith@cs.unc.edu>
29 .\" Modified 1995-05-18 by Todd Larason <jtl@molehill.org>
30 .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
31 .\" Modified 1995-01-09 by Richard Kettlewell <richard@greenend.org.uk>
32 .\" Modified 1998-05-13 by Michael Haardt <michael@cantor.informatik.rwth-aachen.de>
33 .\" Modified 1999-07-06 by aeb & Albert Cahalan
34 .\" Modified 2000-01-07 by aeb
35 .\" Modified 2004-06-23 by Michael Kerrisk <mtk.manpages@gmail.com>
36 .\" 2007-06-08 mtk: Added example program
37 .\" 2007-07-05 mtk: Added details on underlying system call interfaces
39 .TH STAT 2 2021-03-22 "Linux" "Linux Programmer's Manual"
41 stat, fstat, lstat, fstatat \- get file status
44 .B #include <sys/stat.h>
46 .BI "int stat(const char *restrict " pathname ,
47 .BI " struct stat *restrict " statbuf );
48 .BI "int fstat(int " fd ", struct stat *" statbuf );
49 .BI "int lstat(const char *restrict " pathname ,
50 .BI " struct stat *restrict " statbuf );
52 .BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */"
53 .B #include <sys/stat.h>
55 .BI "int fstatat(int " dirfd ", const char *restrict " pathname ,
56 .BI " struct stat *restrict " statbuf ", int " flags );
60 Feature Test Macro Requirements for glibc (see
61 .BR feature_test_macros (7)):
66 /* Since glibc 2.20 */ _DEFAULT_SOURCE
67 || _XOPEN_SOURCE >= 500
68 .\" _XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED
69 || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L
70 || /* Glibc 2.19 and earlier */ _BSD_SOURCE
76 _POSIX_C_SOURCE >= 200809L
81 These functions return information about a file, in the buffer pointed to by
83 No permissions are required on the file itself, but\(emin the case of
87 .BR lstat ()\(emexecute
88 (search) permission is required on all of the directories in
90 that lead to the file.
95 retrieve information about the file pointed to by
106 is a symbolic link, then it returns information about the link itself,
107 not the file that the link refers to.
112 except that the file about which information is to be retrieved
113 is specified by the file descriptor
116 .SS The stat structure
117 All of these system calls return a
119 structure, which contains the following fields:
124 dev_t st_dev; /* ID of device containing file */
125 ino_t st_ino; /* Inode number */
126 mode_t st_mode; /* File type and mode */
127 nlink_t st_nlink; /* Number of hard links */
128 uid_t st_uid; /* User ID of owner */
129 gid_t st_gid; /* Group ID of owner */
130 dev_t st_rdev; /* Device ID (if special file) */
131 off_t st_size; /* Total size, in bytes */
132 blksize_t st_blksize; /* Block size for filesystem I/O */
133 blkcnt_t st_blocks; /* Number of 512B blocks allocated */
135 /* Since Linux 2.6, the kernel supports nanosecond
136 precision for the following timestamp fields.
137 For the details before Linux 2.6, see NOTES. */
139 struct timespec st_atim; /* Time of last access */
140 struct timespec st_mtim; /* Time of last modification */
141 struct timespec st_ctim; /* Time of last status change */
143 #define st_atime st_atim.tv_sec /* Backward compatibility */
144 #define st_mtime st_mtim.tv_sec
145 #define st_ctime st_ctim.tv_sec
151 the order of fields in the
153 structure varies somewhat
154 across architectures.
156 the definition above does not show the padding bytes
157 that may be present between some fields on various architectures.
158 Consult the glibc and kernel source code
159 if you need to know the details.
161 .\" Background: inode attributes are modified with i_mutex held, but
162 .\" read by stat() without taking the mutex.
164 for performance and simplicity reasons, different fields in the
166 structure may contain state information from different moments
167 during the execution of the system call.
172 is changed by another process by calling
179 together with the new
183 together with the new
188 structure are as follows:
191 This field describes the device on which this file resides.
196 macros may be useful to decompose the device ID in this field.)
199 This field contains the file's inode number.
202 This field contains the file type and mode.
205 for further information.
208 This field contains the number of hard links to the file.
211 This field contains the user ID of the owner of the file.
214 This field contains the ID of the group owner of the file.
217 This field describes the device that this file (inode) represents.
220 This field gives the size of the file (if it is a regular
221 file or a symbolic link) in bytes.
222 The size of a symbolic link is the length of the pathname
223 it contains, without a terminating null byte.
226 This field gives the "preferred" block size for efficient filesystem I/O.
229 This field indicates the number of blocks allocated to the file,
231 (This may be smaller than
233 when the file has holes.)
236 This is the time of the last access of file data.
239 This is the time of last modification of file data.
242 This is the file's last status change timestamp
243 (time of last change to the inode).
245 For further information on the above fields, see
251 system call is a more general interface for accessing file information
252 which can still provide exactly the behavior of each of
258 If the pathname given in
260 is relative, then it is interpreted relative to the directory
261 referred to by the file descriptor
263 (rather than relative to the current working directory of
264 the calling process, as is done by
268 for a relative pathname).
278 is interpreted relative to the current working
279 directory of the calling process (like
291 can either be 0, or include one or more of the following flags ORed:
293 .BR AT_EMPTY_PATH " (since Linux 2.6.39)"
294 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
297 is an empty string, operate on the file referred to by
299 (which may have been obtained using the
305 can refer to any type of file, not just a directory, and
308 is similar to that of
314 the call operates on the current working directory.
315 This flag is Linux-specific; define
317 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
318 to obtain its definition.
320 .BR AT_NO_AUTOMOUNT " (since Linux 2.6.38)"
321 Don't automount the terminal ("basename") component of
323 if it is a directory that is an automount point.
324 This allows the caller to gather attributes of an automount point
325 (rather than the location it would mount).
327 .\" commit 42f46148217865a545e129612075f3d828a2c4e4
328 also don't instantiate a nonexistent name in an
329 on-demand directory such as used for automounter indirect maps.
331 flag has no effect if the mount point has already been mounted over.
343 can be used in tools that scan directories
344 to prevent mass-automounting of a directory of automount points.
346 This flag is Linux-specific; define
348 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
349 to obtain its definition.
351 .B AT_SYMLINK_NOFOLLOW
354 is a symbolic link, do not dereference it:
355 instead return information about the link itself, like
359 dereferences symbolic links, like
364 for an explanation of the need for
367 On success, zero is returned.
368 On error, \-1 is returned, and
370 is set to indicate the error.
374 Search permission is denied for one of the directories
375 in the path prefix of
378 .BR path_resolution (7).)
382 is not a valid open file descriptor.
388 Too many symbolic links encountered while traversing the path.
397 does not exist or is a dangling symbolic link.
401 is an empty string and
407 Out of memory (i.e., kernel memory).
410 A component of the path prefix of
418 refers to a file whose size, inode number,
419 or number of blocks cannot be represented in, respectively, the types
424 This error can occur when, for example,
425 an application compiled on a 32-bit platform without
426 .I \-D_FILE_OFFSET_BITS=64
429 on a file whose size exceeds
433 The following additional errors can occur for
438 is not a valid file descriptor.
441 Invalid flag specified in
448 is a file descriptor referring to a file other than a directory.
451 was added to Linux in kernel 2.6.16;
452 library support was added to glibc in version 2.4.
457 SVr4, 4.3BSD, POSIX.1-2001, POSIX.1.2008.
458 .\" SVr4 documents additional
460 .\" error conditions EINTR, ENOLINK, and EOVERFLOW. SVr4
461 .\" documents additional
465 .\" error conditions EINTR, EMULTIHOP, ENOLINK, and EOVERFLOW.
470 According to POSIX.1-2001,
472 on a symbolic link need return valid information only in the
474 field and the file type of the
479 POSIX.1-2008 tightens the specification, requiring
481 to return valid information in all fields except the mode bits in
488 fields may be less portable.
489 (They were introduced in BSD.
490 The interpretation differs between systems,
491 and possibly on a single system when NFS mounts are involved.)
494 Older kernels and older standards did not support nanosecond timestamp
496 Instead, there were three timestamp
497 .RI fields\(em st_atime ,
500 .IR st_ctime \(emtyped
503 that recorded timestamps with one-second precision.
505 Since kernel 2.5.48, the
507 structure supports nanosecond resolution for the three file timestamp fields.
508 The nanosecond components of each timestamp are available
509 via names of the form
510 .IR st_atim.tv_nsec ,
511 if suitable feature test macros are defined.
512 Nanosecond timestamps were standardized in POSIX.1-2008,
513 and, starting with version 2.12,
514 glibc exposes the nanosecond component names if
516 is defined with the value 200809L or greater, or
518 is defined with the value 700 or greater.
519 Up to and including glibc 2.19,
520 the definitions of the nanoseconds components are also defined if
525 If none of the aforementioned macros are defined,
526 then the nanosecond values are exposed with names of the form
529 .SS C library/kernel differences
530 Over time, increases in the size of the
532 structure have led to three successive versions of
544 on 32-bit platforms such as i386.
545 The first two versions were already present in Linux 1.0
546 (albeit with different names);
547 .\" See include/asm-i386/stat.h in the Linux 2.4 source code for the
548 .\" various versions of the structure definitions
549 the last was added in Linux 2.4.
550 Similar remarks apply for
555 The kernel-internal versions of the
557 structure dealt with by the different versions are, respectively:
559 .IR __old_kernel_stat
560 The original structure, with rather narrow fields, and no padding.
565 field and padding added to various parts of the structure to
566 allow for future expansion.
576 fields to accommodate the Linux-2.4 expansion of UIDs and GIDs to 32 bits,
577 and various other enlarged fields and further padding in the structure.
578 (Various padding bytes were eventually consumed in Linux 2.6,
579 with the advent of 32-bit device IDs and nanosecond components
580 for the timestamp fields.)
584 wrapper function hides these details from applications,
585 invoking the most recent version of the system call provided by the kernel,
586 and repacking the returned information if required for old binaries.
588 .\" A note from Andries Brouwer, July 2007
590 .\" > Is the story not rather more complicated for some calls like
593 .\" Yes and no, mostly no. See /usr/include/sys/stat.h .
595 .\" The idea is here not so much that syscalls change, but that
596 .\" the definitions of struct stat and of the types dev_t and mode_t change.
597 .\" This means that libc (even if it does not call the kernel
598 .\" but only calls some internal function) must know what the
599 .\" format of dev_t or of struct stat is.
600 .\" The communication between the application and libc goes via
601 .\" the include file <sys/stat.h> that defines a _STAT_VER and
602 .\" _MKNOD_VER describing the layout of the data that user space
603 .\" uses. Each (almost each) occurrence of stat() is replaced by
604 .\" an occurrence of xstat() where the first parameter of xstat()
605 .\" is this version number _STAT_VER.
607 .\" Now, also the definitions used by the kernel change.
608 .\" But glibc copes with this in the standard way, and the
609 .\" struct stat as returned by the kernel is repacked into
610 .\" the struct stat as expected by the application.
611 .\" Thus, _STAT_VER and this setup cater for the application-libc
612 .\" interface, rather than the libc-kernel interface.
614 .\" (Note that the details depend on gcc being used as c compiler.)
616 On modern 64-bit systems, life is simpler: there is a single
618 system call and the kernel deals with a
620 structure that contains fields of a sufficient size.
622 The underlying system call employed by the glibc
624 wrapper function is actually called
626 or, on some architectures,
627 .\" strace(1) shows the name "newfstatat" on x86-64
630 The following program calls
632 and displays selected fields in the returned
637 #include <sys/types.h>
638 #include <sys/stat.h>
643 #include <sys/sysmacros.h>
646 main(int argc, char *argv[])
651 fprintf(stderr, "Usage: %s <pathname>\en", argv[0]);
655 if (lstat(argv[1], &sb) == \-1) {
660 printf("ID of containing device: [%jx,%jx]\en",
661 (uintmax_t) major(sb.st_dev),
662 (uintmax_t) minor(sb.st_dev));
664 printf("File type: ");
666 switch (sb.st_mode & S_IFMT) {
667 case S_IFBLK: printf("block device\en"); break;
668 case S_IFCHR: printf("character device\en"); break;
669 case S_IFDIR: printf("directory\en"); break;
670 case S_IFIFO: printf("FIFO/pipe\en"); break;
671 case S_IFLNK: printf("symlink\en"); break;
672 case S_IFREG: printf("regular file\en"); break;
673 case S_IFSOCK: printf("socket\en"); break;
674 default: printf("unknown?\en"); break;
677 printf("I\-node number: %ju\en", (uintmax_t) sb.st_ino);
679 printf("Mode: %jo (octal)\en",
680 (uintmax_t) sb.st_mode);
682 printf("Link count: %ju\en", (uintmax_t) sb.st_nlink);
683 printf("Ownership: UID=%ju GID=%ju\en",
684 (uintmax_t) sb.st_uid, (uintmax_t) sb.st_gid);
686 printf("Preferred I/O block size: %jd bytes\en",
687 (intmax_t) sb.st_blksize);
688 printf("File size: %jd bytes\en",
689 (intmax_t) sb.st_size);
690 printf("Blocks allocated: %jd\en",
691 (intmax_t) sb.st_blocks);
693 printf("Last status change: %s", ctime(&sb.st_ctime));
694 printf("Last file access: %s", ctime(&sb.st_atime));
695 printf("Last file modification: %s", ctime(&sb.st_mtime));
709 .BR capabilities (7),