# stat

## NAME



           stat, fstat, lstat, fstatat - get file status
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <sys/stat.h>**
    
           **int stat(const char *restrict** _path_**,**
                    **struct stat *restrict** _statbuf_**);**
           **int fstat(int** _fd_**, struct stat ***_statbuf_**);**
           **int lstat(const char *restrict** _path_**,**
                    **struct stat *restrict** _statbuf_**);**
    
           **#include <fcntl.h>           **/* Definition of **AT_*** constants */
           **#include <sys/stat.h>**
    
           **int fstatat(int** _dirfd_**, const char *restrict** _path_**,**
                    **struct stat *restrict** _statbuf_**, int** _flags_**);**
    
       Feature Test Macro Requirements for glibc (see
       feature_test_macros(7)):
    
           **lstat**():
               /* Since glibc 2.20 */ _DEFAULT_SOURCE
                   || _XOPEN_SOURCE >= 500
                   || /* Since glibc 2.10: */ _POSIX_C_SOURCE >= 200112L
                   || /* glibc 2.19 and earlier */ _BSD_SOURCE
    
           **fstatat**():
               Since glibc 2.10:
                   _POSIX_C_SOURCE >= 200809L
               Before glibc 2.10:
                   _ATFILE_SOURCE
    


## DESCRIPTION



           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 _path_
           that lead to the file.
    
           **stat**() and **fstatat**() retrieve information about the file pointed
           to by _path_ ; the differences for **fstatat**() are described below.
    
           **lstat**() is identical to **stat**(), except that if _path_ 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_.
    
       **The stat structure**
           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_.
    
       **fstatat()**
           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 _path_ 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 _path_ is relative and _dirfd_ is the special value **AT_FDCWD** , then
           _path_ is interpreted relative to the current working directory of
           the calling process (like **stat**() and **lstat**()).
    
           If _path_ is absolute, then _dirfd_ is ignored.
    
           _flags_ can either be 0, or include one or more of the following
           flags ORed:
    
           **AT_EMPTY_PATH**(since Linux 2.6.39)
                  If _path_ is an empty string (or NULL, since Linux 6.11)
                  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.
    
           **AT_NO_AUTOMOUNT**(since Linux 2.6.38)
                  Don't automount the terminal ("basename") component of
                  _path._  Since Linux 3.1 this flag is ignored.  Since Linux
                  4.11 this flag is implied.
    
           **AT_SYMLINK_NOFOLLOW**
                  If _path_ 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 to indicate the error.
    


## ERRORS



           **EACCES** Search permission is denied for one of the directories in
                  the path prefix of _path_.  (See also path_resolution(7).)
    
           **EBADF** _fd_ is not a valid open file descriptor.
    
           **EBADF**(**fstatat**()) _path_ is relative but _dirfd_ is neither **AT_FDCWD**
                  nor a valid file descriptor.
    
           **EFAULT** Bad address.
    
           **EINVAL**(**fstatat**()) Invalid flag specified in _flags_.
    
           **ELOOP** Too many symbolic links encountered while traversing the
                  path.
    
           **ENAMETOOLONG**
                  _path_ is too long.
    
           **ENOENT** A component of _path_ does not exist or is a dangling
                  symbolic link.
    
           **ENOENT** _path_ is an empty string and **AT_EMPTY_PATH** was not specified
                  in _flags_.
    
           **ENOMEM** Out of memory (i.e., kernel memory).
    
           **ENOTDIR**
                  A component of the path prefix of _path_ is not a directory.
    
           **ENOTDIR**
                  (**fstatat**()) _path_ is relative and _dirfd_ is a file descriptor
                  referring to a file other than a directory.
    
           **EOVERFLOW**
                  _path_ or _fd_ refers to a file whose size, inode number, or
                  number of blocks cannot be represented in, respectively,
                  the types _off_t_ , _ino_t_ , or _blkcnt_t_.  This error can occur
                  when, for example, an application compiled on a 32-bit
                  platform without _-D_FILE_OFFSET_BITS=64_ calls **stat**() on a
                  file whose size exceeds _(1 <<31)-1_ bytes.
    


## STANDARDS



           POSIX.1-2008.
    


## EXAMPLES



           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 <path>\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);
           }
    


* * *