Функции _stat, _wstat

Статья
06/09/2015

Получите сведения о состоянии файла.

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 
);

Параметры

path
Указатель на строку, содержащую путь к существующему файлу или каталогу.
buffer
Указатель на структуру, которая хранит результаты.

Возвращаемое значение

Каждая из этих функций возвращает 0, если получена информация о состоянии файла. Возвращаемое значение -1 указывает на ошибку, в случае которой errno имеет значение ENOENT, указывая, что имя файла или путь не могут быть найдены. Возвращаемое значение EINVAL указывает на недопустимый параметр; errno также имеет значение EINVAL в этом случае.

Примечание

Если path содержит расположение каталога, он не может содержать конечную обратную косую черту.В этом случае будет возвращено -1 и errno будет равно ENOENT.

См. раздел _doserrno, errno, _sys_errlist, and _sys_nerr для дополнительных сведений по этим и другим кодам возврата.

Отметку даты в файле можно представить, если она позже полуночи 1-го января 1970 и раньше 23:59:59 31-го декабря 3000, время в формате UTC, если только не используется _stat32 или _wstat32 или определено _USE_32BIT_TIME_T, в этом случае дата может быть представлена только до 03:14:07 19-го января 2038, время в формате 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 работает корректно с символьными ссылками.

Эта функция проверяет свои параметры. Если path или buffer равно NULL, то вызывается обработчик недопустимого параметра, как описано в Проверка параметров.

Вариации типов Time и File Length _stat

Функции	Определен ли_USE_32BIT_TIME_T?	Тип Time.	Тип File length
_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

Структура _stat, определенная в SYS\STAT.H, включает следующие поля.

st_gid
Числовой идентификатор группы, содержащей файл (только для UNIX). Это поле всегда будет равно нулю в системах Windows. Перенаправленный файл классифицируется как файл 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
Всегда 1 в файловых системах, не являющихся NTFS.
st_rdev
Номер диска, содержащего файл (то же, что и st_dev).
st_size
Размер файла в байтах. 64-разрядное целое число для вариантов с суффиксом i64**.**
st_uid
Числовой идентификатор пользователя, который владеет файлом (только для UNIX). Это поле всегда будет равно нулю в системах Windows. Перенаправленный файл классифицируется как файл Windows.

Если path ссылается на устройство, то st_size, различные поля времени, поля st_dev и st_rdev в структуре _stat бессмысленны. Поскольку STAT.H использует тип _dev_t, который определен в TYPES.H, необходимо включить 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 );
   }
}