gmtime_s, _gmtime32_s, _gmtime64_s

Artigo
06/09/2015

Converte um valor de tempo em uma estrutura. Essas são versões de _gmtime32, _gmtime64 com aprimoramentos de segurança conforme descrito em Recursos de segurança no CRT.

errno_t gmtime_s(
   struct tm* _tm,
   const __time_t* time
);
errno_t _gmtime32_s(
   struct tm* _tm,
   const __time32_t* time
);
errno_t _gmtime64_s(
   struct tm* _tm,
   const __time64_t* time 
);

Parâmetros

_tm
Ponteiro para uma estrutura de tm . Os campos da estrutura retornada contêm o valor avaliado do argumento timer em UTC em vez de na hora local.
time
Ponteiro para o momento armazenados. O tempo é representado como segundos passados desde a meia-noite (00:00: 00) de 1º de janeiro de 1970, UTC (tempo universal coordenado).

Valor de retorno

Nulo se com êxito. O valor de retorno é um código de erro se houver uma falha. Os códigos de erro são definidos em Errno.h; para uma lista desses erros, consulte errno.

Condições de erro

_tm	time	Return	Valor em _tm
NULL	any	EINVAL	Não modificados.
Não NULL (pontos para a memória válido)	NULL	EINVAL	Todos os campos definidos como -1.
Não NULL	< 0	EINVAL	Todos os campos definidos como -1.

No caso das primeiras duas condições de erro, o manipulador inválido do parâmetro é chamado, conforme descrito em Validação do parâmetro. Se a execução puder continuar, essas funções definirão errno como EINVAL e retornarão EINVAL.

Comentários

A função de _gmtime32_s divide o valor de time e o coloca em uma estrutura de tipo tm, definida em Time.h. O endereço da estrutura for transmitido em _tm. O valor de time geralmente é obtido de uma chamada à função de time .

Dica

O ambiente de destino deve tentar determinar se o tempo do horário de verão estão em vigor.A biblioteca de tempo de execução C assumirá as regras dos Estados Unidos para implementar o cálculo de horário de verão.

Cada um dos campos de estrutura é do tipo int, conforme mostrado na seguinte tabela.

tm_sec
Segundos após o minuto (0 a 59).
tm_min
Minutos após a hora (0 – 59).
tm_hour
Horas a partir da meia-noite (0 – 23).
tm_mday
Dia do mês (1 – 31).
tm_mon
Mês (0 – 11; janeiro = 0).
tm_year
Ano (o ano atual menos 1900).
tm_wday
Dia da semana (de 0 a 6; domingo = 0).
tm_yday
Dia do ano (de 0 a 365; 1 de janeiro = 0).
tm_isdst
Sempre 0 para gmtime.

_gmtime64_s, que usa a estrutura de __time64_t , permite que as datas são expressas anterior a 23:59: o 31 de dezembro, 59, 3000, UTC; considerando que gmtime32_s representa apenas datas a 03:14: 7 de janeiro de 19, 2038, UTC. A meia-noite, o 1º de janeiro de 1970, é o limite inferior do intervalo de datas para essas duas funções.

gmtime_s é uma função embutida que é avaliada para _gmtime64_s e time_t é equivalente a __time64_t. Se você precisar forçar o compilador para interpretar time_t como time_tde 32 bits antigo, você pode definir _USE_32BIT_TIME_T. Isso causará gmtime_s na ser alinhado a _gmtime32_s. Isso não é recomendado porque seu aplicativo pode falhar depois do 18 de janeiro de 2038, e não é permitido em plataformas de 64 bits.

Requisitos

Rotina	Cabeçalho necessário
gmtime_s	<time.h>
_gmtime32_s	<time.h>
_gmtime64_s	<time.h>

Para obter mais informações sobre compatibilidade, consulte Compatibilidade na Introdução.

Exemplo

// crt_gmtime64_s.c
// This program uses _gmtime64_s to convert a 64-bit
// integer representation of coordinated universal time
// to a structure named newtime, then uses asctime_s to
// convert this structure to an output string.
 

#include <time.h>
#include <stdio.h>

int main( void )
{
   struct tm newtime;
   __int64 ltime;
   char buf[26];
   errno_t err;

   _time64( &ltime );

   // Obtain coordinated universal time: 
   err = _gmtime64_s( &newtime, &ltime );
   if (err)
   {
      printf("Invalid Argument to _gmtime64_s.");
   }
   
   // Convert to an ASCII representation 
   err = asctime_s(buf, 26, &newtime);
   if (err)
   {
      printf("Invalid Argument to asctime_s.");
   }

   printf( "Coordinated universal time is %s\n", 
           buf );
}