Set the file modification time.
int _utime( unsigned char *filename, struct _utimbuf *times );
int _wutime( wchar_t *filename, struct _utimbuf *times );
| Routine | Required Headers | Optional Headers | Compatibility |
| _utime | <sys/utime.h> | <errno.h> | Win 95, Win NT |
| _wutime | <utime.h> or <wchar.h> | <errno.h> | Win 95, Win NT |
For additional compatibility information, see Compatibility in the Introduction.
Libraries
| LIBC.LIB | Single thread static library, retail version |
| LIBCMT.LIB | Multithread static library, retail version |
| MSVCRT.LIB | Import library for MSVCRT.DLL, retail version |
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
Parameters
filename
Path or filename
times
Pointer to stored time values
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 NT and Windows 95, 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 handle to 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 |
Example
/* UTIME.C: This program uses _utime to set the
* file-modification time to the current time.
*/
#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/utime.h>
void main( void )
{
/* Show file time before and after. */
system( "dir utime.c" );
if( _utime( "utime.c", NULL ) == -1 )
perror( "_utime failed\n" );
else
printf( "File time modified\n" );
system( "dir utime.c" );
}
Output
Volume in drive C is ALDONS
Volume Serial Number is 0E17-1702
Directory of C:\dolphin\crt\code
05/03/94 10:00p 451 utime.c
1 File(s) 451 bytes
83,320,832 bytes free
Volume in drive C is ALDONS
Volume Serial Number is 0E17-1702
Directory of C:\dolphin\crt\code
05/03/94 10:00p 451 utime.c
1 File(s) 451 bytes
83,320,832 bytes free
File time modified
See Also asctime, ctime, _fstat, _ftime, _futime, gmtime, localtime, _stat, time