Click above to get retro games delivered to your door ever month!

Synopsis:
    #include <sys\types.h>
    #include <sys\stat.h>
    int fstat( int handle, struct stat *buf );

Description:
    The fstat function obtains information about an open file whose file
    handle is handle.  This information is placed in the structure located
    at the address indicated by buf.

    The file <sys\stat.h> contains definitions for the structure  stat.

    struct stat {
       dev_t   st_dev;    /* disk drive file resides on */
       ino_t   st_ino;    /* this inode's number        */
       unsigned short st_mode; /* file mode             */
       short   st_nlink;  /* # of hard links            */
       short   st_uid;    /* user-id, always 'root'     */
       short   st_gid;    /* group-id, always 'root'    */
       dev_t   st_rdev;   /* drive #, same as st_dev    */
       off_t   st_size;   /* total file size            */
       time_t  st_atime;  /* time of last access        */
       time_t  st_mtime;  /* time of last modification  */
       time_t  st_ctime;  /* time of last status change */
    };
    At least the following macros are defined in the <sys\stat.h> header
    file.

    S_ISFIFO(m)
        Test for FIFO.

    S_ISCHR(m)
        Test for character special file.

    S_ISDIR(m)
        Test for directory file.

    S_ISBLK(m)
        Test for block special file.

    S_ISREG(m)
        Test for regular file.

    The value m supplied to the macros is the value of the  st_mode field of
    a  stat structure.  The macro evaluates to a non-zero value if the test
    is true and zero if the test is false.

    The following bits are encoded within the  st_mode field of a  stat
    structure.

    S_IRWXU
        Read, write, search (if a directory), or execute (otherwise)

    S_IRUSR
        Read permission bit

    S_IWUSR
        Write permission bit

    S_IXUSR
        Search/execute permission bit

    S_IREAD
        ==  S_IRUSR (for Microsoft compatibility)

    S_IWRITE
        ==  S_IWUSR (for Microsoft compatibility)

    S_IEXEC
        ==  S_IXUSR (for Microsoft compatibility)

     S_IRWXU is the bitwise inclusive OR of  S_IRUSR,  S_IWUSR, and
     S_IXUSR.

    S_IRWXG
        Read, write, search (if a directory), or execute (otherwise)

    S_IRGRP
        Read permission bit

    S_IWGRP
        Write permission bit

    S_IXGRP
        Search/execute permission bit

     S_IRWXG is the bitwise inclusive OR of  S_IRGRP,  S_IWGRP, and
     S_IXGRP.

    S_IRWXO
        Read, write, search (if a directory), or execute (otherwise)

    S_IROTH
        Read permission bit

    S_IWOTH
        Write permission bit

    S_IXOTH
        Search/execute permission bit

     S_IRWXO is the bitwise inclusive OR of  S_IROTH,  S_IWOTH, and
     S_IXOTH.

    S_ISUID
        (Not supported by DOS, OS/2 or Windows NT) Set user ID on execution.
         The process's effective user ID shall be set to that of the owner
        of the file when the file is run as a program.  On a regular file,
        this bit should be cleared on any write.

    S_ISGID
        (Not supported by DOS, OS/2 or Windows NT) Set group ID on
        execution.  Set effective group ID on the process to the file's
        group when the file is run as a program.  On a regular file, this
        bit should be cleared on any write.


Returns:
    The fstat function returns zero when the information is successfully
    obtained.  Otherwise, -1 is returned.

Errors:
    When an error has occurred,  errno contains a value indicating the type
    of error that has been detected.

    EBADF
        The handle argument is not a valid file handle.


See Also:
    creat, dup, dup2, open, sopen, stat

Example:
    #include <stdio.h>
    #include <sys\types.h>
    #include <sys\stat.h>
    #include <fcntl.h>
    #include <io.h>

    void main()
      {
        int handle, rc;
        struct stat buf;

        handle = open( "file", O_RDONLY );
        if( handle != -1 ) {
          rc = fstat( handle, &buf );
          if( rc != -1 )
            printf( "File size = %d\n", buf.st_size );
          close( handle );
        }
      }

Classification:
    POSIX 1003.1

Systems:
    All