_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:
errno valor |
Condição |
|---|---|
EACCES |
O caminho especifica o diretório ou o arquivo somente leitura |
EINVAL |
Argumento times inválido |
EMFILE |
Há muitos arquivos abertos (o arquivo deve ser aberto para seu tempo de modificação ser alterado) |
ENOENT |
Caminho ou nome de arquivo não encontrado |
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:
| Campo | Descrição |
|---|---|
actime |
Horário de acesso ao arquivo |
modtime |
Horário de modificação do arquivo |
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
| Rotina TCHAR.H | _UNICODE e _MBCS não definidos |
_MBCS definido |
_UNICODE definido |
|---|---|---|---|
_tutime |
_utime |
_utime |
_wutime |
_tutime32 |
_utime32 |
_utime32 |
_wutime32 |
_tutime64 |
_utime64 |
_utime64 |
_wutime64 |
Requisitos
| Rotina | Cabeçalhos necessários | Cabeçalhos opcionais |
|---|---|---|
_utime, _utime32, _utime64 |
<sys/utime.h> | <errno.h> |
_utime64 |
<sys/utime.h> | <errno.h> |
_wutime |
<utime.h> ou <wchar.h> | <errno.h> |
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