# fstatat

## PROLOG



           This manual page is part of the POSIX Programmer's Manual.  The
           Linux implementation of this interface may differ (consult the
           corresponding Linux manual page for details of Linux behavior), or
           the interface may not be implemented on Linux.
    


## NAME



           fstatat, lstat, stat — get file status
    


## SYNOPSIS



           #include <fcntl.h>
           #include <sys/stat.h>
    
           int fstatat(int fd, const char *restrict _path_ ,
               struct stat *restrict _buf_ , int _flag_);
           int lstat(const char *restrict _path_ , struct stat *restrict _buf_);
           int stat(const char *restrict _path_ , struct stat *restrict _buf_);
    


## DESCRIPTION



           The _stat_() function shall obtain information about the named file
           and write it to the area pointed to by the _buf_ argument. The _path_
           argument points to a pathname naming a file. Read, write, or
           execute permission of the named file is not required. An
           implementation that provides additional or alternate file access
           control mechanisms may, under implementation-defined conditions,
           cause _stat_() to fail. In particular, the system may deny the
           existence of the file specified by _path_.
    
           If the named file is a symbolic link, the _stat_() function shall
           continue pathname resolution using the contents of the symbolic
           link, and shall return information pertaining to the resulting
           file if the file exists.
    
           The _buf_ argument is a pointer to a **stat** structure, as defined in
           the _< sys/stat.h>_ header, into which information is placed
           concerning the file.
    
           The _stat_() function shall update any time-related fields (as
           described in the Base Definitions volume of POSIX.1‐2017, _Section_
           _4.9_ , _File Times Update_), before writing into the **stat** structure.
    
           If the named file is a shared memory object, the implementation
           shall update in the **stat** structure pointed to by the _buf_ argument
           the _st_uid_ , _st_gid_ , _st_size_ , and _st_mode_ fields, and only the
           S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file
           permission bits need be valid. The implementation may update other
           fields and flags.
    
           If the named file is a typed memory object, the implementation
           shall update in the **stat** structure pointed to by the _buf_ argument
           the _st_uid_ , _st_gid_ , _st_size_ , and _st_mode_ fields, and only the
           S_IRUSR, S_IWUSR, S_IRGRP, S_IWGRP, S_IROTH, and S_IWOTH file
           permission bits need be valid. The implementation may update other
           fields and flags.
    
           For all other file types defined in this volume of POSIX.1‐2017,
           the structure members _st_mode_ , _st_ino_ , _st_dev_ , _st_uid_ , _st_gid_ ,
           _st_atim_ , _st_ctim_ , and _st_mtim_ shall have meaningful values and the
           value of the member _st_nlink_ shall be set to the number of links
           to the file.
    
           The _lstat_() function shall be equivalent to _stat_(), except when
           _path_ refers to a symbolic link. In that case _lstat_() shall return
           information about the link, while _stat_() shall return information
           about the file the link references.
    
           For symbolic links, the _st_mode_ member shall contain meaningful
           information when used with the file type macros. The file mode
           bits in _st_mode_ are unspecified. The structure members _st_ino_ ,
           _st_dev_ , _st_uid_ , _st_gid_ , _st_atim_ , _st_ctim_ , and _st_mtim_ shall have
           meaningful values and the value of the _st_nlink_ member shall be
           set to the number of (hard) links to the symbolic link.  The value
           of the _st_size_ member shall be set to the length of the pathname
           contained in the symbolic link not including any terminating null
           byte.
    
           The _fstatat_() function shall be equivalent to the _stat_() or
           _lstat_() function, depending on the value of _flag_ (see below),
           except in the case where _path_ specifies a relative path. In this
           case the status shall be retrieved from a file relative to the
           directory associated with the file descriptor _fd_ instead of the
           current working directory. If the access mode of the open file
           description associated with the file descriptor is not O_SEARCH,
           the function shall check whether directory searches are permitted
           using the current permissions of the directory underlying the file
           descriptor. If the access mode is O_SEARCH, the function shall not
           perform the check.
    
           Values for _flag_ are constructed by a bitwise-inclusive OR of flags
           from the following list, defined in _< fcntl.h>_:
    
           AT_SYMLINK_NOFOLLOW
                 If _path_ names a symbolic link, the status of the symbolic
                 link is returned.
    
           If _fstatat_() is passed the special value AT_FDCWD in the _fd_
           parameter, the current working directory shall be used and the
           behavior shall be identical to a call to _stat_() or _lstat_()
           respectively, depending on whether or not the AT_SYMLINK_NOFOLLOW
           bit is set in _flag_.
    


## RETURN VALUE



           Upon successful completion, these functions shall return 0.
           Otherwise, these functions shall return -1 and set _errno_ to
           indicate the error.
    


## ERRORS



           These functions shall fail if:
    
           **EACCES** Search permission is denied for a component of the path
                  prefix.
    
           **EIO** An error occurred while reading from the file system.
    
           **ELOOP** A loop exists in symbolic links encountered during
                  resolution of the _path_ argument.
    
           **ENAMETOOLONG**
                  The length of a component of a pathname is longer than
                  {NAME_MAX}.
    
           **ENOENT** A component of _path_ does not name an existing file or _path_
                  is an empty string.
    
           **ENOTDIR**
                  A component of the path prefix names an existing file that
                  is neither a directory nor a symbolic link to a directory,
                  or the _path_ argument contains at least one non-<slash>
                  character and ends with one or more trailing <slash>
                  characters and the last pathname component names an
                  existing file that is neither a directory nor a symbolic
                  link to a directory.
    
           **EOVERFLOW**
                  The file size in bytes or the number of blocks allocated to
                  the file or the file serial number cannot be represented
                  correctly in the structure pointed to by _buf_.
    
           The _fstatat_() function shall fail if:
    
           **EACCES** The access mode of the open file description associated
                  with _fd_ is not O_SEARCH and the permissions of the
                  directory underlying _fd_ do not permit directory searches.
    
           **EBADF** The _path_ argument does not specify an absolute path and the
                  _fd_ argument is neither AT_FDCWD nor a valid file descriptor
                  open for reading or searching.
    
           **ENOTDIR**
                  The _path_ argument is not an absolute path and _fd_ is a file
                  descriptor associated with a non-directory file.
    
           These functions may fail if:
    
           **ELOOP** More than {SYMLOOP_MAX} symbolic links were encountered
                  during resolution of the _path_ argument.
    
           **ENAMETOOLONG**
                  The length of a pathname exceeds {PATH_MAX}, or pathname
                  resolution of a symbolic link produced an intermediate
                  result with a length that exceeds {PATH_MAX}.
    
           **EOVERFLOW**
                  A value to be stored would overflow one of the members of
                  the **stat** structure.
    
           The _fstatat_() function may fail if:
    
           **EINVAL** The value of the _flag_ argument is not valid.
    
           _The following sections are informative._
    


## EXAMPLES



       **Obtaining File Status Information**
           The following example shows how to obtain file status information
           for a file named **/home/cnd/mod1**.  The structure variable _buffer_ is
           defined for the **stat** structure.
    
               #include <sys/types.h>
               #include <sys/stat.h>
               #include <fcntl.h>
    
               struct stat buffer;
               int         status;
               ...
               status = stat("/home/cnd/mod1", &buffer);
    
       **Getting Directory Information**
           The following example fragment gets status information for each
           entry in a directory. The call to the _stat_() function stores file
           information in the **stat** structure pointed to by _statbuf_.  The
           lines that follow the _stat_() call format the fields in the **stat**
           structure for presentation to the user of the program.
    
               #include <sys/types.h>
               #include <sys/stat.h>
               #include <dirent.h>
               #include <pwd.h>
               #include <grp.h>
               #include <time.h>
               #include <locale.h>
               #include <langinfo.h>
               #include <stdio.h>
               #include <stdint.h>
    
               struct dirent  *dp;
               struct stat     statbuf;
               struct passwd  *pwd;
               struct group   *grp;
               struct tm      *tm;
               char            datestring[256];
               ...
               /* Loop through directory entries. */
               while ((dp = readdir(dir)) != NULL) {
    
                   /* Get entry's information. */
                   if (stat(dp->d_name, &statbuf) == -1)
                       continue;
    
                   /* Print out type, permissions, and number of links. */
                   printf("%10.10s", sperm (statbuf.st_mode));
                   printf("%4d", statbuf.st_nlink);
    
                   /* Print out owner's name if it is found using getpwuid(). */
                   if ((pwd = getpwuid(statbuf.st_uid)) != NULL)
                       printf(" %-8.8s", pwd->pw_name);
                   else
                       printf(" %-8d", statbuf.st_uid);
    
                   /* Print out group name if it is found using getgrgid(). */
                   if ((grp = getgrgid(statbuf.st_gid)) != NULL)
                       printf(" %-8.8s", grp->gr_name);
                   else
                       printf(" %-8d", statbuf.st_gid);
    
                   /* Print size of file. */
                   printf(" %9jd", (intmax_t)statbuf.st_size);
    
                   tm = localtime(&statbuf.st_mtime);
    
                   /* Get localized date string. */
                   strftime(datestring, sizeof(datestring), nl_langinfo(D_T_FMT), tm);
    
                   printf(" %s %s\n", datestring, dp->d_name);
               }
    
       **Obtaining Symbolic Link Status Information**
           The following example shows how to obtain status information for a
           symbolic link named **/modules/pass1**.  The structure variable _buffer_
           is defined for the **stat** structure. If the _path_ argument specified
           the pathname for the file pointed to by the symbolic link
           (**/home/cnd/mod1**), the results of calling the function would be the
           same as those returned by a call to the _stat_() function.
    
               #include <sys/stat.h>
    
               struct stat buffer;
               int status;
               ...
               status = lstat("/modules/pass1", &buffer);
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           The intent of the paragraph describing ``additional or alternate
           file access control mechanisms'' is to allow a secure
           implementation where a process with a label that does not dominate
           the file's label cannot perform a _stat_() function. This is not
           related to read permission; a process with a label that dominates
           the file's label does not need read permission.  An implementation
           that supports write-up operations could fail _fstat_() function
           calls even though it has a valid file descriptor open for writing.
    
           The purpose of the _fstatat_() function is to obtain the status of
           files in directories other than the current working directory
           without exposure to race conditions. Any part of the path of a
           file could be changed in parallel to a call to _stat_(), resulting
           in unspecified behavior. By opening a file descriptor for the
           target directory and using the _fstatat_() function it can be
           guaranteed that the file for which status is returned is located
           relative to the desired directory.
    


## FUTURE DIRECTIONS



           None.
    


* * *