_utime, _wutime

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

Time Management Routines

See Also   asctime, ctime, _fstat, _ftime, _futime, gmtime, localtime, _stat, time