# fstat

## 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



           fstat — get file status
    


## SYNOPSIS



           #include <sys/stat.h>
    
           int fstat(int _fildes_ , struct stat *_buf_);
    


## DESCRIPTION



           The _fstat_() function shall obtain information about an open file
           associated with the file descriptor _fildes_ , and shall write it to
           the area pointed to by _buf_.
    
           If _fildes_ references 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 _fildes_ references 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.
    
           The _buf_ argument is a pointer to a **stat** structure, as defined in
           _< sys/stat.h>_, into which information is placed concerning the
           file.
    
           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 _st_nlink_ member shall be set to the number of links
           to the file.
    
           An implementation that provides additional or alternative file
           access control mechanisms may, under implementation-defined
           conditions, cause _fstat_() to fail.
    
           The _fstat_() 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.
    


## RETURN VALUE



           Upon successful completion, 0 shall be returned. Otherwise, -1
           shall be returned and _errno_ set to indicate the error.
    


## ERRORS



           The _fstat_() function shall fail if:
    
           **EBADF** The _fildes_ argument is not a valid file descriptor.
    
           **EIO** An I/O error occurred while reading from the file system.
    
           **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 _fstat_() function may fail if:
    
           **EOVERFLOW**
                  One of the values is too large to store into the structure
                  pointed to by the _buf_ argument.
    
           _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. The **/home/cnd/mod1** file is opened
           with read/write privileges and is passed to the open file
           descriptor _fildes_.
    
               #include <sys/types.h>
               #include <sys/stat.h>
               #include <fcntl.h>
    
               struct stat buffer;
               int         status;
               ...
               fildes = open("/home/cnd/mod1", O_RDWR);
               status = fstat(fildes, &buffer);
    


## APPLICATION USAGE



           None.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *