_utime, _utime32, _utime64, _wutime, _wutime32, _wutime64

Establece la hora de modificación de un archivo.

Sintaxis

int _utime(
   const char *filename,
   struct _utimbuf *times
);
int _utime32(
   const char *filename,
   struct __utimbuf32 *times
);
int _utime64(
   const char *filename,
   struct __utimbuf64 *times
);
int _wutime(
   const wchar_t *filename,
   struct _utimbuf *times
);
int _wutime32(
   const wchar_t *filename,
   struct __utimbuf32 *times
);
int _wutime64(
   const wchar_t *filename,
   struct __utimbuf64 *times
);

Parámetros

filename
Puntero a una cadena que contiene la ruta de acceso o el nombre de archivo.

times
Puntero a los valores de hora almacenados.

Valor devuelto

Si se ha cambiado la hora de modificación de archivo, cada una de estas funciones devuelve 0. Un valor devuelto de -1 indica un error. Si se pasa un parámetro no válido, se invoca el controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, estas funciones devuelven -1 y errno se establecen en uno de los valores siguientes:

Valor de errno	Condición
EACCES	La ruta de acceso especifica un directorio o un archivo de solo lectura
EINVAL	Argumento times no válido
EMFILE	Demasiados archivos abiertos (se debe abrir el archivo para cambiar su hora de modificación)
ENOENT	Ruta de acceso o nombre de archivo no encontrado

Para obtener más información sobre los códigos de retorno, vea errno, _doserrno, _sys_errlist y _sys_nerr.

La fecha de un archivo se puede cambiar si la fecha de modificación es posterior a la medianoche del 1 de enero de 1970 y anterior a la fecha de finalización de la función empleada. _utime y _wutime usan un valor de hora de 64 bits, por lo que la fecha de finalización es 23:59:59, 31 de diciembre de 3000, UTC. Si _USE_32BIT_TIME_T se define para forzar el comportamiento anterior, la fecha de finalización es 23:59:59, 18 de enero de 2038, UTC. _utime32 o _wutime32 usan un tipo de hora de 32 bits independientemente de si _USE_32BIT_TIME_T está definido y siempre tienen la fecha de finalización más temprana. _utime64 o _wutime64 usan siempre el tipo de hora de 64 bits, por lo que en todo momento admiten la fecha de finalización más tardía.

Comentarios

La _utime función establece el tiempo de modificación del archivo especificado por filename. El proceso debe tener acceso de escritura al archivo para cambiar la hora. En el sistema operativo Windows, puede cambiar la hora de acceso y de modificación en la estructura _utimbuf. Si times es un puntero NULL, la hora de modificación se establece en la hora local actual. De lo contrario, times debe apuntar a una estructura de tipo _utimbuf, definida en SYS\UTIME.H.

La estructura _utimbuf almacena las horas de acceso a archivos y de modificación usadas por _utime para cambiar las fechas de modificación de archivos. La estructura tiene los dos campos siguientes, que son de tipo time_t:

Campo	Descripción
actime	Hora de acceso a archivos
modtime	Hora de modificación de archivos

Las versiones específicas de la estructura _utimbuf (__utimbuf32 y __utimbuf64) se definen mediante las versiones de 32 y 64 bits del tipo de hora. Estas estructuras se usan en las versiones específicas de 32 y 64 bits de esta función. _utimbuf de forma predeterminada usa un tipo de hora de 64 bits, a menos que _USE_32BIT_TIME_T esté definido.

_utime es idéntico a _futime, excepto que el argumento filename de _utime es un nombre de archivo o una ruta de acceso a un archivo en lugar de un descriptor de archivo de un archivo abierto.

_wutime es una versión con caracteres anchos de _utime; el argumento filename para _wutime es una cadena de caracteres anchos. Por lo demás, estas funciones se comportan exactamente igual.

De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiar este comportamiento, consulte Estado global en CRT.

Asignaciones de rutinas de texto genérico

Rutina TCHAR.H	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_tutime	_utime	_utime	_wutime
_tutime32	_utime32	_utime32	_wutime32
_tutime64	_utime64	_utime64	_wutime64

Requisitos

Routine	Encabezados obligatorios	Encabezados opcionales
_utime, _utime32, _utime64	<sys/utime.h>	<errno.h>
_utime64	<sys/utime.h>	<errno.h>
_wutime	<utime.h> o <wchar.h>	<errno.h>

Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Ejemplo

Este programa usa _utime para establecer la hora de modificación del archivo en la hora actual.

// crt_utime.c
#include <stdio.h>
#include <stdlib.h>
#include <sys/types.h>
#include <sys/utime.h>
#include <time.h>

int main( void )
{
   struct tm tma = {0}, tmm = {0};
   struct _utimbuf ut;

   // Fill out the accessed time structure
   tma.tm_hour = 12;
   tma.tm_isdst = 0;
   tma.tm_mday = 15;
   tma.tm_min = 0;
   tma.tm_mon = 0;
   tma.tm_sec = 0;
   tma.tm_year = 103;

   // Fill out the modified time structure
   tmm.tm_hour = 12;
   tmm.tm_isdst = 0;
   tmm.tm_mday = 15;
   tmm.tm_min = 0;
   tmm.tm_mon = 0;
   tmm.tm_sec = 0;
   tmm.tm_year = 102;

   // Convert tm to time_t
   ut.actime = mktime(&tma);
   ut.modtime = mktime(&tmm);

   // Show file time before and after
   system( "dir crt_utime.c" );
   if( _utime( "crt_utime.c", &ut ) == -1 )
      perror( "_utime failed\n" );
   else
      printf( "File time modified\n" );
   system( "dir crt_utime.c" );
}

Salida de ejemplo

Volume in drive C has no label.
Volume Serial Number is 9CAC-DE74

Directory of C:\test

01/09/2003  05:38 PM               935 crt_utime.c
               1 File(s)            935 bytes
               0 Dir(s)  20,742,955,008 bytes free
File time modified
Volume in drive C has no label.
Volume Serial Number is 9CAC-DE74

Directory of C:\test

01/15/2002  12:00 PM               935 crt_utime.c
               1 File(s)            935 bytes
               0 Dir(s)  20,742,955,008 bytes free

Consulte también

Administración de tiempo
asctime, _wasctime
ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64
_fstat, _fstat32, _fstat64, _fstati64, _fstat32i64, _fstat64i32
_ftime, _ftime32, _ftime64
_futime, _futime32, _futime64
gmtime, _gmtime32, _gmtime64
localtime, _localtime32, _localtime64
Funciones _stat, _wstat
time, _time32, _time64