_utime, _utime32, _utime64, _wutime, _wutime32, _wutime64

Set the file modification time.

Syntax

int _utime( // See note in remarks section about linkage
   const char *filename,
   struct _utimbuf *times
);
int _utime32(
   const char *filename,
   struct __utimbuf32 *times
);
int _utime64(
   const char *filename,
   struct __utimbuf64 *times
);
int _wutime( // See note in remarks section about linkage
   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
);

Parameters

filename
Pointer to a string that contains the path or filename.

times
Pointer to stored time values.

Return value

Each of these functions returns 0 if the file-modification time was changed. A return value of -1 indicates an error. If an invalid parameter is passed, the invalid parameter handler is invoked, as described in Parameter validation. If execution is allowed to continue, these functions return -1, and errno is set to one of the following values:

For more information about return codes, see errno, _doserrno, _sys_errlist, and _sys_nerr.

The date can be changed for a file if the change date is after midnight, January 1, 1970, and before the end date of the function used. _utime and _wutime use a 64-bit time value, so the end date is 23:59:59, December 31, 3000, UTC. If _USE_32BIT_TIME_T is defined to force the old behavior, the end date is 23:59:59 January 18, 2038, UTC. _utime32 or _wutime32 use a 32-bit time type regardless of whether _USE_32BIT_TIME_T is defined, and always have the earlier end date. _utime64 or _wutime64 always use the 64-bit time type, so these functions always support the later end date.

Remarks

The _utime function sets the modification time for the file specified by filename. The process must have write access to the file in order to change the time. In the Windows operating system, you can change the access time and the modification time in the _utimbuf structure. If times is a NULL pointer, the modification time is set to the current local time. Otherwise, times must point to a structure of type _utimbuf, defined in SYS\UTIME.H.

The _utimbuf structure stores file access and modification times used by _utime to change file-modification dates. The structure has the following fields, which are both of type time_t:

Specific versions of the _utimbuf structure (__utimbuf32 and __utimbuf64) are defined using the 32-bit and 64-bit versions of the time type. These structures are used in the 32-bit and 64-bit specific versions of this function. _utimbuf itself by default uses a 64-bit time type unless _USE_32BIT_TIME_T is defined.

_utime is identical to _futime except that the filename argument of _utime is a filename or a path to a file, rather than a file descriptor of an open file.

_wutime is a wide-character version of _utime; the filename argument to _wutime is a wide-character string. These functions behave identically otherwise.

By default, this function's global state is scoped to the application. To change this behavior, see Global state in the CRT.

Generic-text routine mappings

Requirements

For more compatibility information, see Compatibility.

Example

This program uses _utime to set the file-modification time to the current time.

// 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" );
}

Sample output

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

See also

Time management
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 functions
time, _time32, _time64