_utime, _utime32, _utime64, _wutime, _wutime32, _wutime64

Статья
06/09/2015

Задают время изменения файла.

int _utime(
   const char *filename,
   struct _utimbuf *times 
);
int _utime32(
   const char *filename,
   struct __utimbuf32 *times 
);
int _utime64(
   const char *filename,
   struct __utimbuf64 *times 
);
int _wutime(
   const wchar_t *filename,
   struct _utimbuf *times 
);
int _wutime32(
   const wchar_t *filename,
   struct __utimbuf32 *times 
);
int _wutime64(
   const wchar_t *filename,
   struct __utimbuf64 *times 
);

Параметры

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

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

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

EACCES
Путь указывает каталог или файл, доступный только для чтения
EINVAL
Недопустимый аргумент times.
EMFILE
Слишком много открытых файлов (необходимо открыть файл, чтобы изменить его время изменения)
ENOENT
Файл или путь не найден

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

Даты можно изменить для файла, если дата изменения после полуночи 1-ого января 1970-ого и до конечной даты используемой функции. _utime и _wutime используют 64-разрядное значение времени, поэтому конечная дата 23:59:59, 31-е декабря 3000, время в формате UTC. Если _USE_32BIT_TIME_T определяется для принудительного использования старого поведения, конечная дата 03:14:07, 7-е января 2038, время в формате UTC. _utime32 или _wutime32 используют 32-разрядный тип времени независимо от того, определено ли _USE_32BIT_TIME_T, и всегда имеют меньшую конечную дату. _utime64 или _wutime64 всегда используют 64-разрядный тип времени, поэтому эти функции всегда поддерживают более позднюю конечную дату.

Заметки

Функция _utime задает время изменения для файла, указанного в filename*.* Процесс должен иметь разрешение на запись в файл, чтобы изменять время. В операционной системе Windows можно изменить время доступа и время изменения в структуре _utimbuf. Если times является указателем на NULL, время изменения устанавливается в текущее время. В противном случае times должно указывать на структуру типа _utimbuf, определенную в SYS\UTIME.H.

Структура _utimbuf хранит время доступа к файлу и время изменения файла, которые используются _utime для изменения времени изменения файла. Структура содержит следующие поля, имеющие тип time_t:

actime
Время доступа к файлам
modtime
Время изменения файла

Определенные версии структуры _utimbuf (_utimebuf32 и __utimbuf64) задаются 32- и 64-разрядными версиями типа времени. Они используются в 32- и 64-разрядных версиях этой функции. _utimbuf само по умолчанию использует 64-разрядное время, если тип _USE_32BIT_TIME_T не определен.

_utime совпадает с _futime за исключением того, что аргумент filename функции _utime именем файла или путем к файлу, а не файловым идентификатором открытого файла.

_wutime — двухбайтовая версия _utime; аргумент filename для _wutime - строка двухбайтовых знаков. В остальном эти функции ведут себя идентично.

Универсальное текстовое сопоставление функций

Подпрограмма TCHAR.H	_UNICODE & _MBCS не определены	_MBCS определено	_UNICODE определено
_tutime	_utime	_utime	_wutime
_tutime32	_utime32	_utime32	_wutime32
_tutime64	_utime64	_utime64	_wutime64

Требования

Подпрограмма	Обязательные заголовки	Необязательные заголовки
_utime, _utime32, _utime64	<sys/utime.h>	<errno.h>
_utime64	<sys/utime.h>	<errno.h>
_wutime	<utime.h> or <wchar.h>	<errno.h>

Дополнительные сведения о совместимости см. в разделе Совместимость во введении.

Пример

Эта программа использует _utime для задания времени изменения файлов текущего момента времени.

// crt_utime.c
#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/utime.h>
#include <time.h>

int main( void )
{
   struct tm tma = {0}, tmm = {0};
   struct _utimbuf ut;

   // Fill out the accessed time structure
   tma.tm_hour = 12;
   tma.tm_isdst = 0;
   tma.tm_mday = 15;
   tma.tm_min = 0;
   tma.tm_mon = 0;
   tma.tm_sec = 0;
   tma.tm_year = 103;

   // Fill out the modified time structure
   tmm.tm_hour = 12;
   tmm.tm_isdst = 0;
   tmm.tm_mday = 15;
   tmm.tm_min = 0;
   tmm.tm_mon = 0;
   tmm.tm_sec = 0;
   tmm.tm_year = 102;

   // Convert tm to time_t
   ut.actime = mktime(&tma);
   ut.modtime = mktime(&tmm);

   // Show file time before and after
   system( "dir crt_utime.c" );
   if( _utime( "crt_utime.c", &ut ) == -1 )
      perror( "_utime failed\n" );
   else
      printf( "File time modified\n" );
   system( "dir crt_utime.c" );
}

Пример результатов выполнения

Volume in drive C has no label.
 Volume Serial Number is 9CAC-DE74

 Directory of C:\test

01/09/2003  05:38 PM               935 crt_utime.c
               1 File(s)            935 bytes
               0 Dir(s)  20,742,955,008 bytes free
File time modified
 Volume in drive C has no label.
 Volume Serial Number is 9CAC-DE74

 Directory of C:\test

01/15/2002  12:00 PM               935 crt_utime.c
               1 File(s)            935 bytes
               0 Dir(s)  20,742,955,008 bytes free