_stat, _stat64, _stati64, _wstat, _wstat64, _wstati64

Get status information on a file.

int _stat(
   const char *path,
   struct _stat *buffer 
);
int _stat64(
   const char *path,
   struct __stat64 *buffer 
);
int _stati64(
   const char *path,
   struct _stati64 *buffer 
);
int _wstat(
   const wchar_t *path,
   struct _stat *buffer 
);
int _wstat64(
   const wchar_t *path,
   struct __stat64 *buffer 
);
int _wstati64(
   const wchar_t *path,
   struct _stati64 *buffer 
);

Parameters

path

Pointer to a string containing the path of existing file.

buffer

Pointer to structure that stores results.

Return Value

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.

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 19:14:07 January 18, 2038, UTC unless you use _stat64 or _wstat64, in which case the date can be represented up till 23:59:59, December 31, 3000, UTC.

Remarks

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.

Generic-Text Routine Mappings

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

st_gid

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

st_atime

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

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 _stati64 and _wstati64

st_uid

Numeric identifier of user who owns file (UNIX-specific). This field will always be zero on Windows NT systems. A redirected file is classified as a Windows NT 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.

Requirements

For additional compatibility information, see Compatibility in the Introduction.

Libraries

All versions of the C run-time libraries.

Example

// crt_stat.c
/* This program uses the _stat64 function to
 * report information about the file named stat.c.
 */

#include <time.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <stdio.h>

int main( void )
{
   struct __stat64 buf;
   int result;

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

   /* Check if statistics are valid: */
   if( result != 0 )
      perror( "Problem getting information" );
   else
   {
      /* Output some of the statistics: */
      printf( "File size     : %ld\n", buf.st_size );
      printf( "Drive         : %c:\n", buf.st_dev + 'A' );
      printf( "Time modified : %s", _ctime64( &buf.st_mtime ) );
   }
}

Sample Output

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

See Also

File Handling Routines | _access | _fstat | _getmbcp | _setmbcp | Run-Time Routines and .NET Framework Equivalents