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 );
    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.

    Field     Type/Meaning

st_dev
    (dev_t) the disk drive the file resides on

st_ino
    (ino_t) this inode's number (not used for DOS)

st_mode
    (unsigned short) file mode

st_nlink
    (short) number of hard links

st_uid
    (unsigned long) user-id (always 'root' for DOS)

st_gid
    (short) group-id (always 'root' for DOS)

st_rdev
    (dev_t) this should be the device type but it is the same as st_dev for
    the time being

st_size
    (off_t) total file size

st_atime
    (time_t) this should be the file "last accessed" time if the file system
    supports it

st_mtime
    (time_t) the file "last modified" time

st_ctime
    (time_t) this should be the file "last status change" time if the file
    system supports it

    The following fields are Netware only:

st_btime
    (time_t) the file "last archived" time

st_attr
    (unsigned long) the file's attributes

st_archivedID
    (unsigned long) the user/object ID that last archived file

st_updatedID
    (unsigned long) the user/object ID that last updated file

st_inheritedRightsMask
    (unsigned short) the inherited rights mask

st_originatingNameSpace
    (unsigned char) the originating name space

st_name
    (unsigned char array[_MAX_NAME]) the ASCIIZ filename (null-terminated
    string)

    At least the following macros are defined in the <sys\stat.h> header
    file.

    Macro     Meaning

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.

    Mask     Owner Permissions

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.

    Mask     Group Permissions (same as owner's on DOS, OS/2 or Windows NT)

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.

    Mask     Other Permissions (same as owner's on DOS, OS/2 or Windows NT)

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.

    Mask     Meaning

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.

    The _fstat function is identical to fstat.  Use _fstat for ANSI/ISO
    naming conventions.

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.

    Constant     Meaning

EBADF
    The handle argument is not a valid file handle.

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:
    fstat is POSIX 1003.1, _fstat is not POSIX

_fstat conforms to ANSI/ISO naming conventions

Systems:
     fstat - All, Netware

    _fstat - DOS, Windows, Win386, Win32, OS/2 1.x(all), OS/2-32

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