_utime, _utime64, _wutime, _wutime64

Set the file modification time.

int _utime(
   const char *filename,
   struct _utimbuf *times 
);
int _utime64(
   const char *filename,
   struct __utimbuf64 *times 
);
int _wutime(
   const wchar_t *filename,
   struct _utimbuf *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, in which case errno is set to one of the following values:

EACCES

Path specifies directory or read-only file

EINVAL

Invalid times argument

EMFILE

Too many open files (the file must be opened to change its modification time)

ENOENT

Path or filename not found

See _doserrno, errno, _sys_errlist, and _sys_nerr for more information on these, and other, return codes.

The date can be changed for a file if the change date is after midnight, January 1, 1970, and before 19:14:07 January 18, 2038, UTC (using _utime or _wutime) or before 23:59:59, December 31, 3000, UTC (using _utime64 or _wutime64).

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. Under Windows 98/Me and Windows NT/2000/XP, you can change the access time and the modication 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:

actime

Time of file access

modtime

Time of file modification

_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.

Generic-Text Routine Mappings

Requirements

For additional compatibility information, see Compatibility in the Introduction.

Libraries

All versions of the C run-time libraries.

Example

This program uses _utime64 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>

int main( void )
{
   /* Show file time before and after. */
   system( "dir crt_utime.c" );
   if( _utime64( "crt_utime.c", NULL ) == -1 )
      perror( "crt__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 E078-087A

 Directory of C:\test

02/05/2002  08:12a                 482 crt_utime.c
               1 File(s)            482 bytes
               0 Dir(s)  15,384,121,344 bytes free
File time modified
 Volume in drive C has no label.
 Volume Serial Number is E078-087A

 Directory of C:\test

02/05/2002  08:12a                 482 crt_utime.c
               1 File(s)            482 bytes
               0 Dir(s)  15,384,121,344 bytes free

See Also

Time Management Routines | asctime | ctime | _fstat | _ftime | _futime | gmtime | localtime | _stat | time | Run-Time Routines and .NET Framework Equivalents