_futime, _futime32, _futime64

Sets the modification time on an open file.

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. In Visual C++ 2005, _futime and _utimbufuse 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 19:14:07 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

.NET Framework Equivalent

See Also

Concepts

Time Management