Each of these functions returns 0 if the file-status information is obtained. A return value of –1 indicates an error, in which case errno is set to ENOENT, indicating that the filename or path could not be found. A return value of EINVAL indicates an invalid parameter; errno is also set to EINVAL in this case.

See _doserrno, errno, _sys_errlist, and _sys_nerr for more information on this, and other, return codes.

The date stamp on a file can be represented if it is later than midnight, January 1, 1970, and before 23:59:59, December 31, 3000, UTC, unless you use _stat32 or _wstat32, or have defined _USE_32BIT_TIME_T, in which case the date can be represented only until 03:14:07 January 19, 2038, UTC.

The _stat function obtains information about the file or directory specified by path and stores it in the structure pointed to by buffer. _stat automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use.

_wstat is a wide-character version of _stat; the path argument to _wstat is a wide-character string. _wstat and _stat behave identically except that _wstat does not handle multibyte-character strings.

Variations of these functions support 32- or 64-bit time types, and 32- or 64-bit file lengths. The first numerical suffix (32 or 64) indicates the size of the time type used; the second suffix is either i32 or i64, indicating whether the file size is represented as a 32-bit or 64-bit integer.

In Visual C++ 2005, _stat is equivalent to _stat64i32, and struct _stat contains a 64-bit time. This is true unless _USE_32BIT_TIME_T is defined, in which case the old behavior is in effect; _stat uses a 32-bit time, and struct _stat contains a 32-bit time. The same is true for _stati64.

This function validates its parameters. If either path or buffer is NULL, the invalid parameter handler is invoked, as described in Parameter Validation.

The _stat structure, defined in SYS\STAT.H, includes the following fields.

st_gid

Numeric identifier of group that owns the file (UNIX-specific) This field will always be zero on Windows systems. A redirected file is classified as a Windows file.

st_atime

Time of last access of file. Valid on NTFS but not on FAT formatted disk drives.

st_ctime

Time of creation of file. Valid on NTFS but not on FAT formatted disk drives.

st_dev

Drive number of the disk containing the file (same as st_rdev).

st_ino

Number of the information node (the inode) for the file (UNIX-specific). On UNIX file systems, the inode describes the file date and time stamps, permissions, and content. When files are hard-linked to one another, they share the same inode. The inode, and therefore st_ino, has no meaning in the FAT, HPFS, or NTFS file systems.

st_mode

Bit mask for file-mode information. The _S_IFDIR bit is set if path specifies a directory; the _S_IFREG bit is set if path specifies an ordinary file or a device. User read/write bits are set according to the file's permission mode; user execute bits are set according to the filename extension.

st_mtime

Time of last modification of file.

st_nlink

Always 1 on non-NTFS file systems.

st_rdev

Drive number of the disk containing the file (same as st_dev).

st_size

Size of the file in bytes; a 64-bit integer for variations with the i64 suffix.

st_uid

Numeric identifier of user who owns file (UNIX-specific). This field will always be zero on Windows systems. A redirected file is classified as a Windows file.

If path refers to a device, the st_size, various time fields, st_dev, and st_rdev fields in the _stat structure are meaningless. Because STAT.H uses the _dev_t type that is defined in TYPES.H, you must include TYPES.H before STAT.H in your code.

For additional compatibility information, see Compatibility in the Introduction.

// crt_stat.c
// This program uses the _stat function to
// report information about the file named crt_stat.c.
 
#include <time.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <stdio.h>
#include <errno.h>

int main( void )
{
   struct _stat buf;
   int result;
   char timebuf[26];
   char* filename = "crt_stat.c";
   errno_t err;

   // Get data associated with "crt_stat.c": 
   result = _stat( filename, &buf );

   // Check if statistics are valid: 
   if( result != 0 )
   {
      perror( "Problem getting information" );
      switch (errno)
      {
         case ENOENT:
           printf("File %s not found.\n", filename);
           break;
         case EINVAL:
           printf("Invalid parameter to _stat.\n");
           break;
         default:
           /* Should never be reached. */
           printf("Unexpected error in _stat.\n");
      }
   }
   else
   {
      // Output some of the statistics: 
      printf( "File size     : %ld\n", buf.st_size );
      printf( "Drive         : %c:\n", buf.st_dev + 'A' );
      err = ctime_s(timebuf, 26, &buf.st_mtime);
      if (err)
      {
         printf("Invalid arguments to ctime_s.");
         exit(1);
      }
      printf( "Time modified : %s", timebuf );
   }
}

Sample Output

File size     : 732
Drive         : C:
Time modified : Thu Feb 07 14:39:36 2002

• System::IO::File::GetAttributes

• System::IO::File::GetCreationTime

• System::IO::File::GetLastAccessTime

• System::IO::File::GetLastWriteTime

Reference