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

Synopsis:
    #include <sys\stat.h>
    int stat( const char *path, struct stat *buf );
    int _stat( const char *path, struct _stat *buf );
    int _wstat( const wchar_t *path, struct _wstat *buf );

Description:
    The stat function obtains information about the file or directory
    referenced in path.  This information is placed in the structure located
    at the address indicated by buf.

    The _stat function is identical to stat.  Use _stat for ANSI/ISO naming
    conventions.

    The _wstat function is a wide-character version of stat that operates
    with 16-bit wide-character strings.  The  _wstat structure contains a
    wide-character version of the Netware st_name field.

    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.


Returns:
    The stat 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.
    EACCES
        Search permission is denied for a component of path.


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

    void main()
      {
        struct stat buf;

        if( stat( "file", &buf ) != -1 ) {
          printf( "File size = %d\n", buf.st_size );
        }
      }

Classification:
    stat is POSIX 1003.1, _stat is not POSIX, _wstat is not POSIX

_stat conforms to ANSI/ISO naming conventions

Systems:
     stat - All, Netware

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

See Also:
    fstat