_utime, _utime32, _utime64, _wutime, _wutime32, , _wutime64

Defina a hora de modificação do arquivo.

Sintaxe

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
Ponteiro para uma cadeia de caracteres que contém o caminho ou nome de arquivo.

times
Ponteiro para os valores temporais armazenados.

Valor retornado

Cada uma dessas funções retornará 0 se a hora de modificação do arquivo for alterada. Um valor retornado de -1 indica que há um erro. Se um parâmetro inválido for passado, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, essas funções retornarão -1 e errno serão definidas como um dos seguintes valores:

Para obter mais informações sobre códigos de retorno, confira errno, _doserrno, _sys_errlist e _sys_nerr.

A data de um arquivo poderá ser alterada se tal alteração ocorrer após a meia-noite de 1º de janeiro de 1970 e antes que a data de término da função seja utilizada. _utime e _wutime usam um valor temporal de 64 bits, assim, a data de término será às 23:59:59 de 31 de dezembro de 3000 (UTC). Se _USE_32BIT_TIME_T for definido para forçar o comportamento antigo, a data de término será às 23:59:59 de 18 de janeiro de 2038 (UTC). _utime32 ou _wutime32 usam um tipo temporal de 32 bits, independentemente de _USE_32BIT_TIME_T estar definido e sempre têm a data de término mais antiga. _utime64 ou _wutime64 sempre usam o tipo temporal de 64 bits para que essas funções ofereçam suporte à data de término mais recente.

Comentários

A _utime função define o tempo de modificação para o arquivo especificado por filename. O processo deve ter acesso de gravação ao arquivo para alterar a hora. No sistema operacional Windows, é possível alterar os horários de acesso e de modificação na estrutura _utimbuf. Se times for um ponteiro NULL, a modificação da hora será definida como o horário local atual. Caso contrário, times deve apontar para uma estrutura do tipo _utimbuf, definida em SYS\UTIME.H.

A estrutura _utimbuf armazena os horários de acesso e modificação usados por _utime para alterar datas de modificação dos arquivos. A estrutura tem os seguintes campos, ambos do tipo time_t:

Versões específicas da estrutura _utimbuf (__utimbuf32 e __utimbuf64) são definidas usando as versões de 32 e 64 bits do tipo temporal. Essas estruturas são usadas nas versões específicas de 32 bits e 64 bits dessa função. O _utimbuf, por padrão, usa um tipo temporal de 64 bits, a menos que _USE_32BIT_TIME_T esteja definido.

_utime é idêntico a _futime, exceto se o argumento filename de _utime for um nome de arquivo ou caminho para um arquivo, em vez de um descritor de arquivo de um arquivo aberto.

A função _wutime é uma versão de caractere largo da função _utime; o argumento filename para _wutime é uma cadeia de caracteres larga. Caso contrário, essas funções se comportam de forma idêntica.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Mapeamentos de rotina de texto genérico

Requisitos

Para obter informações sobre compatibilidade, consulte Compatibilidade.

Exemplo

Esse programa usa _utime para definir a hora de modificação do arquivo como a hora atual.

// 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" );
}

Saída de exemplo

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

Confira também

Gerenciamento de tempo
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
_stat, _wstat funções
time, _time32, _time64