stat, fstat, lstat, fstatat - get file status
#include <sys/stat.h>
int stat(const char *restrict pathname,
struct stat *restrict statbuf);
int fstat(int fd, struct stat *statbuf);
int lstat(const char *restrict pathname,
struct stat *restrict statbuf);
#include <fcntl.h> /* Definition of AT_* constants */
#include <sys/stat.h>
int fstatat(int dirfd, const char *restrict pathname,
struct stat *restrict statbuf, int flags);Feature Test Macro Requirements for glibc (see feature_test_macros(7)):
These functions return information about a file, in the buffer
pointed to by statbuf. 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 the link refers
to.
fstat() is identical to stat(),
except that the file about which information is to be retrieved is
specified by the file descriptor fd.
All of these system calls return a stat structure (see
stat(3type)).
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 st_mode or st_uid is changed by another process by
calling chmod(2) or chown(2),
stat() might return the old st_mode together
with the new st_uid, or the old st_uid together with
the new st_mode.
The fstatat() system call is a more general interface for accessing file information which can still provide exactly the behavior of each of stat(), lstat(), and fstat().
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() and
lstat() for a relative pathname).
If pathname is relative and dirfd is the special
value AT_FDCWD, then pathname is interpreted
relative to the current working directory of the calling process (like
stat() and lstat()).
If pathname is absolute, then dirfd is ignored.
flags can either be 0, or include one or more of the
following flags ORed:
If pathname is an empty string, operate on the file referred
to by dirfd (which may have been obtained using the
open(2) O_PATH flag). In this case,
dirfd can refer to any type of file, not just a directory, and
the behavior of fstatat() is similar to that of
fstat(). If dirfd is
AT_FDCWD, the call operates on the current working
directory. This flag is Linux-specific; define
_GNU_SOURCE to obtain its definition.
Don't automount the terminal ("basename") component of
pathname. Since Linux 3.1 this flag is ignored. Since Linux
4.11 this flag is implied.
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().)
On success, zero is returned. On error, -1 is returned, and
errno is set to indicate the error.
The following program calls lstat() and displays
selected fields in the returned stat structure.
#include <stdint.h>
#include <stdio.h>
#include <stdlib.h>
#include <sys/stat.h>
#include <sys/sysmacros.h>
#include <time.h>
int
main(int argc, char *argv[])
{
struct stat sb;
if (argc != 2) {
fprintf(stderr, "Usage: %s <pathname>\n", argv[0]);
exit(EXIT_FAILURE);
}
if (lstat(argv[1], &sb) == -1) {
perror("lstat");
exit(EXIT_FAILURE);
}
printf("ID of containing device: [%x,%x]\n",
major(sb.st_dev),
minor(sb.st_dev));
printf("File type: ");
switch (sb.st_mode & S_IFMT) {
case S_IFBLK: printf("block device\n"); break;
case S_IFCHR: printf("character device\n"); break;
case S_IFDIR: printf("directory\n"); break;
case S_IFIFO: printf("FIFO/pipe\n"); break;
case S_IFLNK: printf("symlink\n"); break;
case S_IFREG: printf("regular file\n"); break;
case S_IFSOCK: printf("socket\n"); break;
default: printf("unknown?\n"); break;
}
printf("I-node number: %ju\n", (uintmax_t) sb.st_ino);
printf("Mode: %jo (octal)\n",
(uintmax_t) sb.st_mode);
printf("Link count: %ju\n", (uintmax_t) sb.st_nlink);
printf("Ownership: UID=%ju GID=%ju\n",
(uintmax_t) sb.st_uid, (uintmax_t) sb.st_gid);
printf("Preferred I/O block size: %jd bytes\n",
(intmax_t) sb.st_blksize);
printf("File size: %jd bytes\n",
(intmax_t) sb.st_size);
printf("Blocks allocated: %jd\n",
(intmax_t) sb.st_blocks);
printf("Last status change: %s", ctime(&sb.st_ctime));
printf("Last file access: %s", ctime(&sb.st_atime));
printf("Last file modification: %s", ctime(&sb.st_mtime));
exit(EXIT_SUCCESS);
}