_utime, _utime64, _wutime, _wutime64
TOC
Collapse the table of content
Expand the table of content
Important This document may not represent best practices for current development, links to downloads and other resources may no longer be valid. Current recommended version can be found here. ArchiveDisclaimer

_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

TCHAR.H routine _UNICODE & _MBCS not defined _MBCS defined _UNICODE defined
_tutime _utime _utime _wutime
_tutime64 _utime64 _utime64 _wutime64

Requirements

Routine Required headers Optional headers Compatibility
_utime <sys/utime.h> <errno.h> Win 98, Win Me, Win NT, Win 2000, Win XP
_utime64 <sys/utime.h> <errno.h> Win 98, Win Me, Win NT, Win 2000, Win XP
_wutime <utime.h> or <wchar.h> <errno.h> Win 98, Win Me, Win NT, Win 2000, Win XP
_wutime64 <utime.h> or <wchar.h> <errno.h> Win 98, Win Me, Win NT, Win 2000, Win XP

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

Show:
© 2016 Microsoft