gmtime_s, _gmtime32_s, _gmtime64_s

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

Sintaxe

errno_t gmtime_s(
   struct tm* tmDest,
   const __time_t* sourceTime
);
errno_t _gmtime32_s(
   struct tm* tmDest,
   const __time32_t* sourceTime
);
errno_t _gmtime64_s(
   struct tm* tmDest,
   const __time64_t* sourceTime
);

Parâmetros

tmDest
Ponteiro para uma estrutura tm. Os campos da estrutura retornada contêm o valor avaliado do argumento timer no horário UTC e não no horário local.

sourceTime
Ponteiro para a hora armazenada. A hora é representada como os segundos transcorridos desde a meia-noite (00:00:00) de 1º de janeiro de 1970, no horário UTC (Tempo Universal Coordenado).

Valor retornado

Zero se for bem-sucedido. Se houver uma falha, o valor retornado será um código de erro. Códigos de erro são definidos em Errno.h; para obter uma lista desses erros, consulte errno.

Condições de erro

tmDest	sourceTime	Return	Valor em tmDest
NULL	qualquer	EINVAL	Não modificado.
Não é NULL (aponta para a memória válida)	NULL	EINVAL	Todos os campos definidos como -1.
Não é NULL	< 0	EINVAL	Todos os campos definidos como -1.

As primeiras duas condições de erro invoca o manipulador de parâmetro inválido, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, essas funções definirão errno como EINVAL e retornarão EINVAL.

Comentários

A função _gmtime32_s divide o valor de sourceTime e o armazena em uma estrutura do tipo tm, definida em Time.h. O endereço da estrutura é passada em tmDest. O valor de sourceTime frequentemente é obtido com uma chamada para a função time.

Cada um dos campos da estrutura é do tipo int, conforme mostrado na tabela a seguir.

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

_gmtime64_s, que usa a estrutura __time64_t, permite que as datas sejam expressas até 23:59:59 de 31 de dezembro de 3000, no UTC, enquanto gmtime32_s representa apenas datas até 23:59:59 de 18 de janeiro de 2038, no UTC. Meia-noite de 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 como _gmtime64_s e time_t é equivalente a __time64_t. Se você precisar forçar o compilador a interpretar time_t como o time_t antigo de 32 bits, poderá definir _USE_32BIT_TIME_T. _USE_32BIT_TIME_T faz com que gmtime_s seja embutido como _gmtime32_s. Não recomendamos _USE_32BIT_TIME_T, pois seu aplicativo poderá falhar após 18 de janeiro de 2038 e por que isso não é permitido em plataformas de 64 bits.

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

Requisitos

Rotina	Cabeçalho C necessário	Cabeçalho C++ necessário
gmtime_s, _gmtime32_s, _gmtime64_s	<time.h>	<ctime> ou <time.h>

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

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

Coordinated universal time is Fri Apr 25 20:12:33 2003

Confira também

Gerenciamento de tempo
asctime_s, _wasctime_s
ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64
_ftime, _ftime32, _ftime64
gmtime, _gmtime32, _gmtime64
localtime_s, _localtime32_s, _localtime64_s
_mkgmtime, _mkgmtime32, _mkgmtime64
mktime, _mktime32, _mktime64
time, _time32, _time64