_stat, _wstat Functions
Get status information on a file.
int _stat( const char *path, struct _stat *buffer ); int _stat32( const char *path, struct __stat32 *buffer ); int _stat64( const char *path, struct __stat64 *buffer ); int _stati64( const char *path, struct _stati64 *buffer ); int _stat32i64(str const char *path, struct _stat32i64 *buffer ); int _stat64i32(str const char *path, struct _stat64i32 *buffer ); int _wstat( const wchar_t *path, struct _stat *buffer ); int _wstat32( const wchar_t *path, struct __stat32 *buffer ); int _wstat64( const wchar_t *path, struct __stat64 *buffer ); int _wstati64( const wchar_t *path, struct _stati64 *buffer ); int _wstat32i64( const wchar_t *path, struct _stat32i64 *buffer ); int _wstat64i32( const wchar_t *path, struct _stat64i32 *buffer );
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.
Note |
|---|
If path contains the location of a directory, it cannot contain a trailing backslash. If it does, -1 will be returned and errno will be set to ENOENT. |
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.
_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.
Note |
|---|
_wstat does not work with Windows Vista symbolic links. In these cases, _wstat will always report a file size of 0. _stat does work correctly with symbolic links. |
This function validates its parameters. If either path or buffer is NULL, the invalid parameter handler is invoked, as described in Parameter Validation.
Functions | _USE_32BIT_TIME_T defined? | Time type | File length type |
|---|---|---|---|
_stat, _wstat | Not defined | 64-bit | 32-bit |
_stat, _wstat | Defined | 32-bit | 32-bit |
_stat32, _wstat32 | Not affected by the macro definition | 32-bit | 32-bit |
_stat64, _wstat64 | Not affected by the macro definition | 64-bit | 64-bit |
_stati64, _wstati64 | Not defined | 64-bit | 64-bit |
_stati64, _wstati64 | Defined | 32-bit | 64-bit |
_stat32i64, _wstat32i64 | Not affected by the macro definition | 32-bit | 64-bit |
_stat64i32, _wstat64i32 | Not affected by the macro definition | 64-bit | 32-bit |
TCHAR.H routine | _UNICODE & _MBCS not defined | _MBCS defined | _UNICODE defined |
|---|---|---|---|
_tstat | _stat | _stat | _wstat |
_tstat64 | _stat64 | _stat64 | _wstat64 |
_tstati64 | _stati64 | _stati64 | _wstati64 |
_tstat32i64 | _stat32i64 | _stat32i64 | _wstat32i64 |
_tstat64i32 | _stat64i32 | _stat64i32 | _wstat64i32 |
The _stat structure, defined in SYS\STAT.H, includes the following fields.
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.
Routine | Required header | Optional headers |
|---|---|---|
_stat, _stat32, _stat64, _stati64, _stat32i64, _stat64i32 | <sys/types.h> followed by <sys/stat.h> | <errno.h> |
_wstat, _wstat32, _wstat64, _wstati64, _wstat32i64, _wstat64i32 | <sys/types.h> followed by <sys/stat.h> or <wchar.h> | <errno.h> |
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 );
}
}
File size : 732 Drive : C: Time modified : Thu Feb 07 14:39:36 2002
Note