_stat, _stat32, _stat64, _stati64, _stat32i64, _stat64i32, _wstat, _wstat32, _wstat64, _wstati64, _wstat32i64, _wstat64i32

  • 项目

获取文件状态信息。

语法

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(
   const char *path,
   struct _stat32i64 *buffer
);
int _stat64i32(
   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
);

参数

path
指向字符串的指针，该字符串包含现有文件或目录的路径。

buffer
指向存储结果的结构的指针。

返回值

如果获取到文件状态信息，则这些函数将返回 0。 返回值 -1 表示错误，在这种情况下，errno 设置为 ENOENT，表示找不到文件名或路径。 返回值为 EINVAL 表示参数无效；这种情况下 errno 还会设置为 EINVAL 。

有关返回代码的详细信息，请参阅 errno、_doserrno、_sys_errlist 和 _sys_nerr。

如果文件上的日期戳晚于 1970 年 1 月 1 日午夜，且早于 3000 年 12 月 31 日 23:59:59 (UTC)，就可以表示该日期戳，除非使用 _stat32 或 _wstat32，或已定义 _USE_32BIT_TIME_T，在这种情况下只能表示 2038 年 1 月 18 日 23:59:59 (UTC) 之前的日期。

备注

_stat 函数可获取有关 path 指定的文件或目录的信息，并将其存储在 buffer指向的结构中。 _stat 将根据情况自动处理多字节字符串参数，根据当前正在使用的多字节代码页识别多字节字符序列。

_wstat 是 _stat的宽字符版本； path 的 _wstat 参数是宽字符字符串。 _wstat 和 _stat 的行为方式相同，只不过 _wstat 不处理多字节字符字符串。

这些函数的变体支持 32 位或 64 位时间类型以及 32 位或 64 位文件长度。 第一个数字后缀（32 或 64）表示所用时间类型的大小；第二个后缀是 i32 或 i64，表示以 32 位还是 64 位整数表示文件大小。

_stat 等效于 _stat64i32，并且 struct _stat 包含 64 位时间，除非定义了 _USE_32BIT_TIME_T，在这种情况下旧行为有效；_stat 使用 32 位时间，并且 struct _stat 包含 32 位时间。 这一点也适用于 _stati64。

注意

_wstat 不适用于 Windows Vista 符号链接。 在这些情况下， _wstat 将始终报告文件大小为 0。 _stat 适用于符号链接。 _stat 系列函数在 Visual Studio 2015 中使用 CreateFile，而不是 Visual Studio 2013 及更早版本中的 FindFirstFile。 这意味着，如果路径引用目录，则以斜线结尾的路径上的 _stat 会成功，而不像之前，函数会因将 errno 设置为 ENOENT 而出错。

此函数验证其参数。 如果 path 或 buffer 是 NULL，则会调用无效参数处理程序，如参数验证中所述。

默认情况下，此函数的全局状态范围限定为应用程序。 若要更改此行为，请参阅 CRT 中的全局状态。

_stat 的时间类型和文件长度类型变体

函数 _USE_32BIT_TIME_T 已定义 时间类型 文件长度类型
_stat，_wstat 未定义 64 位 32 位
_stat，_wstat 已定义 32 位 32 位
_stat32，_wstat32 不受宏定义影响 32 位 32 位
_stat64，_wstat64 不受宏定义影响 64 位 64 位
_stati64，_wstati64 未定义 64 位 64 位
_stati64，_wstati64 已定义 32 位 64 位
_stat32i64，_wstat32i64 不受宏定义影响 32 位 64 位
_stat64i32，_wstat64i32 不受宏定义影响 64 位 32 位

一般文本例程映射

TCHAR.H 例程 _UNICODE 和 _MBCS 未定义 _MBCS 已定义 _UNICODE 已定义
_tstat _stat _stat _wstat
_tstat64 _stat64 _stat64 _wstat64
_tstati64 _stati64 _stati64 _wstati64
_tstat32i64 _stat32i64 _stat32i64 _wstat32i64
_tstat64i32 _stat64i32 _stat64i32 _wstat64i32

SYS\STAT.H 中定义的 _stat 结构包含下列字段。

字段 说明
st_gid 拥有此文件的组的数字标识符（针对 UNIX）。在 Windows 系统上此字段始终为 0。 重定向的文件分类为 Windows 文件。
st_atime 上次访问文件的时间。 在 NTFS 上有效，但在 FAT 格式的磁盘驱动器上无效。
st_ctime 文件的创建时间。 在 NTFS 上有效，但在 FAT 格式的磁盘驱动器上无效。
st_dev 包含文件的磁盘的驱动器号（与 st_rdev相同）。
st_ino 文件的信息节点号 ( inode)（针对 UNIX）。 在 UNIX 文件系统上， inode 描述文件日期和时间戳、权限和内容。 当文件硬链接到另一文件时，它们共享同一个 inode。 inode和 st_ino在 FAT、HPFS 或 NTFS 文件系统中没有任何意义。
st_mode 文件模式信息的位掩码。 如果 _S_IFDIR 指定目录，会设置 path 位；如果 _S_IFREG 指定一个普通文件或设备，会设置 path 位。 根据文件的权限模式设置用户读/写位；根据文件扩展名设置用户执行位。
st_mtime 上次修改文件的时间。
st_nlink 在非 NTFS 文件系统上始终为 1。
st_rdev 包含文件的磁盘的驱动器号（与 st_dev相同）。
st_size 文件大小，以字节为单位；带有 i64 后缀的变体为 64 位整数。
st_uid 拥有文件的用户的数字标识符（针对 UNIX）。 此字段在 Windows 系统上始终为 0。 重定向的文件分类为 Windows 文件。

如果 path 指的是一种设备，则 st_size、各种时间字段、 st_dev和 st_rdev 结构中的 _stat 字段没有意义。 由于 STAT.H 使用在 TYPES.H 中定义的 _dev_t 类型，因此你必须在代码中包含 TYPES.H，且将其置于 STAT.H 前面。

要求

例程 必需的标头 可选标头
_stat, _stat32, _stat64, _stati64, _stat32i64, _stat64i32 <sys/types.h> 后接 <sys/stat.h> <errno.h>
_wstat, _wstat32, _wstat64, _wstati64, _wstat32i64, _wstat64i32 <sys/types.h> 后跟 <sys/stat.h> 或 <wchar.h> <errno.h>

有关兼容性的详细信息，请参阅 兼容性。

示例

// 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

另请参阅

文件处理
_access、_waccess
_fstat、_fstat32、_fstat64、_fstati64、_fstat32i64、_fstat64i32
_getmbcp
_setmbcp