NAME
stat, fstat, lstat, fstatat - get file status SYNOPSIS
#include
#include
#include
int stat(const char *pathname, struct stat *buf); int fstat(int fd, struct stat *buf); int lstat(const char *pathname, struct stat *buf); #include
/* Definition of AT* constants */ #include
int fstatat(int dirfd, const char *pathname, struct stat *buf, int flags); Feature Test Macro Requirements for glibc (see featuretestmacros(7)): lstat(): /* glibc 2.19 and earlier */ BSDSOURCE || /* Since glibc 2.20 */ DEFAULTSOURCE || XOPENSOURCE >= 500 || /* Since glibc 2.10: */ POSIXCSOURCE >= 200112L fstatat(): Since glibc 2.10: POSIXCSOURCE >= 200809L Before glibc 2.10: ATFILESOURCE DESCRIPTION These functions return information about a file, in the buffer pointed to by buf. No permissions are required on the file itself, but—in the case of stat(), fstatat(), and lstat()—execute (search) permission is required on all of the directories in pathname that lead to the file. stat() and fstatat() retrieve information about the file pointed to by pathname; the differences for fstatat() are described below. lstat() is identical to stat(), except that if pathname is a symbolic link, then it returns information about the link itself, not the file that it refers to. fstat() is identical to stat(), except that the file about which infor‐ mation is to be retrieved is specified by the file descriptor fd. The stat structure All of these system calls return a stat structure, which contains the following fields: struct stat { devt stdev; /* ID of device containing file */ inot stino; /* inode number */ modet stmode; /* file type and mode */ nlinkt stnlink; /* number of hard links */ uidt stuid; /* user ID of owner */ gidt stgid; /* group ID of owner */ devt strdev; /* device ID (if special file) */ offt stsize; /* total size, in bytes */ blksizet stblksize; /* blocksize for filesystem I/O */ blkcntt stblocks; /* number of 512B blocks allocated */ /* Since Linux 2.6, the kernel supports nanosecond precision for the following timestamp fields. For the details before Linux 2.6, see NOTES. */ struct timespec statim; /* time of last access */ struct timespec stmtim; /* time of last modification */ struct timespec stctim; /* time of last status change */ #define statime statim.tvsec /* Backward compatibility */
#define stmtime stmtim.tvsec
#define stctime stctim.tvsec }; Note: the order of fields in the stat structure varies somewhat across architectures. In addition, the definition above does not show the padding bytes that may be present between some fields on various archi‐ tectures. Consult the glibc and kernel source code if you need to know the details. Note: For performance and simplicity reasons, different fields in the stat structure may contain state information from different moments during the execution of the system call. For example, if stmode or stuid is changed by another process by calling chmod(2) or chown(2), stat() might return the old stmode together with the new stuid, or the old stuid together with the new stmode. The fields in the stat structure are as follows: stdev This field describes the device on which this file resides. (The major(3) and minor(3) macros may be useful to decompose the device ID in this field.) stino This field contains the file's inode number. stmode See the discussion of file type and mode, below. stnlink This field contains the number of hard links to the file. stuid This field contains the user ID of the owner of the file. stgid This field contains the ID of the group owner of the file. strdev This field describes the device that this file (inode) repre‐ sents. stsize This field gives the size of the file (if it is a regular file or a symbolic link) in bytes. The size of a symbolic link is the length of the pathname it contains, without a terminating null byte. stblksize This field gives the "preferred" blocksize for efficient filesystem I/O. (Writing to a file in smaller chunks may cause
an inefficient read-modify-rewrite.) stblocks This field indicates the number of blocks allocated to the file,
512-byte units. (This may be smaller than stsize/512 when the file has holes.) statime This is the file's last access timestamp. It is changed by file accesses, for example, by execve(2), mknod(2), pipe(2), utime(2), and read(2) (of more than zero bytes). Other rou‐ tines, like mmap(2), may or may not update statime. stmtime This is the file's last modification timestamp. It is changed by file modifications, for example, by mknod(2), truncate(2), utime(2), and write(2) (of more than zero bytes). Moreover, stmtime of a directory is changed by the creation or deletion of files in that directory. The stmtime field is not changed for changes in owner, group, hard link count, or mode. stctime This is the file's last status change timestamp. It is changed by writing or by setting inode information (i.e., owner, group, link count, mode, etc.). Not all of the Linux filesystems implement all of the time fields. Some filesystem types allow mounting in such a way that file and/or directory accesses do not cause an update of the statime field. (See noatime, nodiratime, and relatime in mount(8), and related information in mount(2).) In addition, statime is not updated if a file is opened with the ONOATIME flag; see open(2). The file type and mode (stmode) POSIX refers to the stmode bits corresponding to the mask SIFMT (see below) as the file type, the 12 bits corresponding to the mask 07777 as the file mode bits and the least significant 9 bits (0777) as the file permission bits. The following mask values are defined for the file type of the stmode field: SIFMT 0170000 bit mask for the file type bit field SIFSOCK 0140000 socket SIFLNK 0120000 symbolic link SIFREG 0100000 regular file SIFBLK 0060000 block device SIFDIR 0040000 directory SIFCHR 0020000 character device SIFIFO 0010000 FIFO Thus, to test for a regular file (for example), one could write: stat(pathname, &sb); if ((sb.stmode & SIFMT) == SIFREG) { /* Handle regular file */ } Because tests of the above form are common, additional macros are defined by POSIX to allow the test of the file type in stmode to be written more concisely: SISREG(m) is it a regular file? SISDIR(m) directory? SISCHR(m) character device? SISBLK(m) block device? SISFIFO(m) FIFO (named pipe)?
SISLNK(m) symbolic link? (Not in POSIX.1-1996.)
SISSOCK(m) socket? (Not in POSIX.1-1996.) The preceding code snippet could thus be rewritten as: stat(pathname, &sb); if (SISREG(sb.stmode)) { /* Handle regular file */ } The definitions of most of the above file type test macros are provided if any of the following feature test macros is defined: BSDSOURCE (in glibc 2.19 and earlier), SVIDSOURCE (in glibc 2.19 and earlier), or DEFAULTSOURCE (in glibc 2.20 and later). In addition, definitions of all of the above macros except SIFSOCK and SISSOCK() are provided if XOPENSOURCE is defined. The definition of SIFSOCK can also be exposed by defining XOPENSOURCE with a value of 500 or greater. The definition of SISSOCK() is exposed if any of the following feature test macros is defined: BSDSOURCE (in glibc 2.19 and earlier), DEFAULTSOURCE (in glibc 2.20 and later), XOPENSOURCE with a value of 500 or greater, or POSIXCSOURCE with a value of 200112L or greater. The following mask values are defined for the file mode component of the stmode field:
SISUID 04000 set-user-ID bit
SISGID 02000 set-group-ID bit (see below) SISVTX 01000 sticky bit (see below) SIRWXU 00700 owner has read, write, and execute permission SIRUSR 00400 owner has read permission SIWUSR 00200 owner has write permission SIXUSR 00100 owner has execute permission SIRWXG 00070 group has read, write, and execute permission SIRGRP 00040 group has read permission SIWGRP 00020 group has write permission SIXGRP 00010 group has execute permission SIRWXO 00007 others (not in group) have read, write, and execute permission SIROTH 00004 others have read permission SIWOTH 00002 others have write permission SIXOTH 00001 others have execute permission
The set-group-ID bit (SISGID) has several special uses. For a direc‐ tory, it indicates that BSD semantics is to be used for that directory: files created there inherit their group ID from the directory, not from the effective group ID of the creating process, and directories created there will also get the SISGID bit set. For a file that does not have
the group execution bit (SIXGRP) set, the set-group-ID bit indicates mandatory file/record locking. The sticky bit (SISVTX) on a directory means that a file in that directory can be renamed or deleted only by the owner of the file, by the owner of the directory, and by a privileged process. fstatat() The fstatat() system call operates in exactly the same way as stat(), except for the differences described here. If the pathname given in pathname is relative, then it is interpreted relative to the directory referred to by the file descriptor dirfd (rather than relative to the current working directory of the calling process, as is done by stat() for a relative pathname). If pathname is relative and dirfd is the special value ATFDCWD, then pathname is interpreted relative to the current working directory of the calling process (like stat()). If pathname is absolute, then dirfd is ignored. flags can either be 0, or include one or more of the following flags ORed: ATEMPTYPATH (since Linux 2.6.39) If pathname is an empty string, operate on the file referred to by dirfd (which may have been obtained using the open(2) OPATH flag). In this case, dirfd can refer to any type of file, not just a directory. If dirfd is ATFDCWD, the call operates on
the current working directory. This flag is Linux-specific; define GNUSOURCE to obtain its definition. ATNOAUTOMOUNT (since Linux 2.6.38) Don't automount the terminal ("basename") component of pathname if it is a directory that is an automount point. This allows the caller to gather attributes of an automount point (rather than the location it would mount). This flag can be used in
tools that scan directories to prevent mass-automounting of a directory of automount points. The ATNOAUTOMOUNT flag has no effect if the mount point has already been mounted over. This
flag is Linux-specific; define GNUSOURCE to obtain its defini‐ tion. ATSYMLINKNOFOLLOW If pathname is a symbolic link, do not dereference it: instead return information about the link itself, like lstat(). (By default, fstatat() dereferences symbolic links, like stat().) See openat(2) for an explanation of the need for fstatat(). RETURN VALUE
On success, zero is returned. On error, -1 is returned, and errno is set appropriately. ERRORS EACCES Search permission is denied for one of the directories in the path prefix of pathname. (See also pathresolution(7).) EBADF fd is not a valid open file descriptor. EFAULT Bad address. ELOOP Too many symbolic links encountered while traversing the path. ENAMETOOLONG pathname is too long. ENOENT A component of pathname does not exist, or pathname is an empty string and ATEMPTYPATH was not specified. ENOMEM Out of memory (i.e., kernel memory). ENOTDIR A component of the path prefix of pathname is not a directory. EOVERFLOW pathname or fd refers to a file whose size, inode number, or number of blocks cannot be represented in, respectively, the types offt, inot, or blkcntt. This error can occur when, for
example, an application compiled on a 32-bit platform without
-DFILEOFFSETBITS=64 calls stat() on a file whose size exceeds
(1<<31)-1 bytes. The following additional errors can occur for fstatat(): EBADF dirfd is not a valid file descriptor. EINVAL Invalid flag specified in flags. ENOTDIR pathname is relative and dirfd is a file descriptor referring to a file other than a directory. VERSIONS fstatat() was added to Linux in kernel 2.6.16; library support was added to glibc in version 2.4. CONFORMING TO
stat(), fstat(), lstat(): SVr4, 4.3BSD, POSIX.1-2001, POSIX.1.2008.
fstatat(): POSIX.1-2008.
According to POSIX.1-2001, lstat() on a symbolic link need return valid information only in the stsize field and the file type of the stmode
field of the stat structure. POSIX.1-2008 tightens the specification, requiring lstat() to return valid information in all fields except the mode bits in stmode. Use of the stblocks and stblksize fields may be less portable. (They were introduced in BSD. The interpretation differs between systems, and possibly on a single system when NFS mounts are involved.) If you need to obtain the definition of the blkcntt or blksizet types from
, then define XOPENSOURCE with the value 500 or greater (before including any header files). POSIX.1-1990 did not describe the SIFMT, SIFSOCK, SIFLNK, SIFREG, SIFBLK, SIFDIR, SIFCHR, SIFIFO, SISVTX constants, but instead specified the use of the macros SISDIR(), and so on. The SIF* con‐
stants are present in POSIX.1-2001 and later.
The SISLNK() and SISSOCK() macros were not in POSIX.1-1996, but both
are present in POSIX.1-2001; the former is from SVID 4, the latter from SUSv2. UNIX V7 (and later systems) had SIREAD, SIWRITE, SIEXEC, where POSIX prescribes the synonyms SIRUSR, SIWUSR, SIXUSR. NOTES On Linux, lstat() will generally not trigger automounter action, whereas stat() will (but see the description of fstatat() ATNOAUTO‐ MOUNT fag, above). For pseudofiles that are autogenerated by the kernel, stat() does not return an accurate value in the stsize field. For example, the value 0 is returned for many files under the /proc directory, while various files under /sys report a size of 4096 bytes, even though the file con‐ tent is smaller. For such files, one should simply try to read as many bytes as possible (and append '\0' to the returned buffer if it is to be interpreted as a string). Timestamp fields Older kernels and older standards did not support nanosecond timestamp fields. Instead, there were three timestamp fields—statime, stmtime,
and stctime—typed as timet that recorded timestamps with one-second precision. Since kernel 2.5.48, the stat structure supports nanosecond resolution for the three file timestamp fields. The nanosecond components of each timestamp are available via names of the form statim.tvnsec, if suit‐ able feature test macros are defined. Nanosecond timestamps were stan‐
dardized in POSIX.1-2008, and, starting with version 2.12, glibc exposes the nanosecond component names if POSIXCSOURCE is defined with the value 200809L or greater, or XOPENSOURCE is defined with the value 700 or greater. Up to and including glibc 2.19, the definitions of the nanoseconds components are also defined if BSDSOURCE or SVIDSOURCE is defined. If none of the aforementioned macros are defined, then the nanosecond values are exposed with names of the form statimensec. Nanosecond timestamps are supported on XFS, JFS, Btrfs, and ext4 (since Linux 2.6.23). Nanosecond timestamps are not supported in ext2, ext3, and Reiserfs. On filesystems that do not support subsecond timestamps, the nanosecond fields are returned with the value 0. C library/kernel differences Over time, increases in the size of the stat structure have led to three successive versions of stat(): sysstat() (slot NRoldstat), sysnewstat() (slot NRstat), and sysstat64() (slot NRstat64) on
32-bit platforms such as i386. The first two versions were already present in Linux 1.0 (albeit with different names); the last was added in Linux 2.4. Similar remarks apply for fstat() and lstat().
The kernel-internal versions of the stat structure dealt with by the different versions are, respectively: oldkernelstat The original structure, with rather narrow fields, and no pad‐ ding. stat Larger stino field and padding added to various parts of the structure to allow for future expansion. stat64 Even larger stino field, larger stuid and stgid fields to
accommodate the Linux-2.4 expansion of UIDs and GIDs to 32 bits, and various other enlarged fields and further padding in the structure. (Various padding bytes were eventually consumed in
Linux 2.6, with the advent of 32-bit device IDs and nanosecond components for the timestamp fields.) The glibc stat() wrapper function hides these details from applica‐ tions, invoking the most recent version of the system call provided by the kernel, and repacking the returned information if required for old binaries.
On modern 64-bit systems, life is simpler: there is a single stat() system call and the kernel deals with a stat structure that contains fields of a sufficient size. The underlying system call employed by the glibc fstatat() wrapper function is actually called fstatat64() or, on some architectures, newfstatat(). EXAMPLE The following program calls stat() and displays selected fields in the returned stat structure.
#include
#include
#include
#include
#include
#include
int main(int argc, char *argv[]) { struct stat sb; if (argc != 2) { fprintf(stderr, "Usage: %s
\n", argv[0]); exit(EXITFAILURE); } if (stat(argv[1], &sb) == -1) { perror("stat"); exit(EXITFAILURE); }
printf("ID of containing device: [%lx,%lx]\n", (long) major(sb.stdev), (long) minor(sb.stdev)); printf("File type: "); switch (sb.stmode & SIFMT) { case SIFBLK: printf("block device\n"); break; case SIFCHR: printf("character device\n"); break; case SIFDIR: printf("directory\n"); break; case SIFIFO: printf("FIFO/pipe\n"); break; case SIFLNK: printf("symlink\n"); break; case SIFREG: printf("regular file\n"); break; case SIFSOCK: printf("socket\n"); break; default: printf("unknown?\n"); break; }
printf("I-node number: %ld\n", (long) sb.stino);
printf("Mode: %lo (octal)\n", (unsigned long) sb.stmode);
printf("Link count: %ld\n", (long) sb.stnlink);
printf("Ownership: UID=%ld GID=%ld\n", (long) sb.stuid, (long) sb.stgid);
printf("Preferred I/O block size: %ld bytes\n", (long) sb.stblksize);
printf("File size: %lld bytes\n", (long long) sb.stsize);
printf("Blocks allocated: %lld\n", (long long) sb.stblocks);
printf("Last status change: %s", ctime(&sb.stctime));
printf("Last file access: %s", ctime(&sb.statime));
printf("Last file modification: %s", ctime(&sb.stmtime)); exit(EXITSUCCESS); } SEE ALSO ls(1), stat(1), access(2), chmod(2), chown(2), readlink(2), utime(2), capabilities(7), symlink(7) COLOPHON
This page is part of release 3.53 of the Linux man-pages project. A description of the project, and information about reporting bugs, can
be found at http://www.kernel.org/doc/man-pages/.
Linux 2017-03-13 STAT(2)