_futime, _futime32, _futime64

Article
06/05/2017

The new home for Visual Studio documentation is Visual Studio 2017 Documentation on docs.microsoft.com.

The latest version of this topic can be found at _futime, _futime32, _futime64.

Sets the modification time on an open file.

Syntax

int _futime(   
   int fd,  
   struct _utimbuf *filetime   
);  
int _futime32(   
   int fd,  
   struct __utimbuf32 *filetime   
);  
int _futime64(   
   int fd,  
   struct __utimbuf64 *filetime   
);

Parameters

fd
File descriptor to the open file.

filetime
Pointer to the structure containing the new modification date.

Return Value

Return 0 if successful. If an error occurs, the invalid parameter handler is invoked, as described in Parameter Validation. If execution is allowed to continue, the function returns –1 and errno is set to EBADF, indicating an invalid file descriptor, or EINVAL, indicating an invalid parameter.

Remarks

The _futime routine sets the modification date and the access time on the open file associated with fd. _futime is identical to _utime, except that its argument is the file descriptor of an open file, rather than the name of a file or a path to a file. The _utimbuf structure contains fields for the new modification date and access time. Both fields must contain valid values. _utimbuf32 and _utimbuf64 are identical to _utimbuf except for the use of the 32-bit and 64-bit time types, respectively. _futime and _utimbuf use a 64-bit time type and _futime is identical in behavior to _futime64. If you need to force the old behavior, define _USE_32BIT_TIME_T. Doing this causes _futime to be identical in behavior to _futime32 and causes the _utimbuf structure to use the 32-bit time type, making it equivalent to __utimbuf32.

_futime64, which uses the __utimbuf64 structure, can read and modify file dates through 23:59:59, December 31, 3000, UTC; whereas a call to _futime32 fails if the date on the file is later than 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for these functions.

Requirements

Function	Required header	Optional header
`_futime`	<sys/utime.h>	<errno.h>
`_futime32`	<sys/utime.h>	<errno.h>
`_futime64`	<sys/utime.h>	<errno.h>

For more compatibility information, see Compatibility in the Introduction.

Example

// crt_futime.c  
// This program uses _futime to set the  
// file-modification time to the current time.  
  
#include <stdio.h>  
#include <stdlib.h>  
#include <fcntl.h>  
#include <io.h>  
#include <sys/types.h>  
#include <sys/stat.h>  
#include <sys/utime.h>  
#include <share.h>  
  
int main( void )  
{  
   int hFile;  
  
   // Show file time before and after.   
   system( "dir crt_futime.c_input" );  
  
   _sopen_s( &hFile, "crt_futime.c_input", _O_RDWR, _SH_DENYNO, 0 );  
  
   if( _futime( hFile, NULL ) == -1 )  
      perror( "_futime failed\n" );  
   else  
      printf( "File time modified\n" );  
  
   _close (hFile);  
  
   system( "dir crt_futime.c_input" );  
}

Input: crt_futime.c_input

Arbitrary file contents.

Sample Output

Volume in drive Z has no label.  
 Volume Serial Number is 5C68-57C1  
  
 Directory of Z:\crt  
  
03/25/2004  10:40 AM                24 crt_futime.c_input  
               1 File(s)             24 bytes  
               0 Dir(s)  24,268,476,416 bytes free  
 Volume in drive Z has no label.  
 Volume Serial Number is 5C68-57C1  
  
 Directory of Z:\crt  
  
03/25/2004  10:41 AM                24 crt_futime.c_input  
               1 File(s)             24 bytes  
               0 Dir(s)  24,268,476,416 bytes free  
File time modified