_utime, _utime32, _utime64, _wutime, _wutime32, _wutime64

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

Синтаксис

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 задаются одно из следующих значений:

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

Дополнительные сведения о кодах возврата см. в разделе errno, _doserrno_sys_errlistи _sys_nerr.

Дату файла можно изменить, если дата изменения лежит в диапазоне от полуночи 1-го января 1970 года до конечной даты используемой функции. В функциях _utime и _wutime используется 64-разрядное значение времени, поэтому конечная дата 23:59:59 31-го декабря 3000 года, время в формате UTC. Если определена директива _USE_32BIT_TIME_T для принудительного использования старого поведения, конечная дата — 23:59:59 18 января 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:

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

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

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

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

По умолчанию глобальное состояние этой функции ограничивается приложением. Чтобы изменить это поведение, см . статью "Глобальное состояние" в CRT.

Сопоставления подпрограмм универсального текста

Подпрограмма 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> или <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

См. также

Управление временем
asctime, _wasctime
ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64
_fstat, _fstat32, _fstat64, _fstati64, _fstat32i64, _fstat64i32
_ftime, _ftime32, _ftime64
_futime, _futime32, _futime64
gmtime, _gmtime32, _gmtime64
localtime, _localtime32, _localtime64
_stat, _wstat функции
time, _time32, _time64