localtime, _localtime32, _localtime64

Artigo
06/09/2015

Converter um valor do tempo e corrija-o para o fuso horário local. Versões mais seguras dessas funções estão disponíveis; consulte localtime_s, _localtime32_s, _localtime64_s.

struct tm *localtime(
   const time_t *timer 
);
struct tm *_localtime32(
   const __time32_t *timer
);
struct tm *_localtime64(
   const __time64_t *timer 
);

Parâmetros

timer
Ponteiro para o momento armazenados.

Valor de retorno

Retorna um ponteiro para o resultado da estrutura, ou NULL se a data passada para a função é:

Antes da meia-noite, o 1º de janeiro de 1970.
Após 03:14: 07, o 19 de janeiro de 2038, UTC (usando _time32 e time32_t).
Após 23:59: o 31 de dezembro, 59, 3000, (UTC usando _time64 e __time64_t).

_localtime64, que usa a estrutura de __time64_t , permite que as datas são expressas anterior a 23:59: o 31 de dezembro, 59, 3000, coordenados hora universal (UTC), enquanto que _localtime32 representar datas a 03:14: 7 de janeiro de 19, 2038, UTC.

localtime é uma função embutida que é avaliada para _localtime64, e time_t é equivalente a __time64_t. Se você precisar forçar o compilador para interpretar time_tcomo time_tde 32 bits antigo, você pode definir _USE_32BIT_TIME_T. Isso fará com que localtime é avaliada para _localtime32. Isso não é recomendado porque seu aplicativo pode falhar depois do 19 de janeiro de 2038, e não é permitido em plataformas de 64 bits.

Os campos do tipo TM da estrutura armazenam os valores a seguir, cada qual é int:

tm_sec
Segundos após o minuto (0 a 59).
tm_min
Minutos após a hora (0 – 59).
tm_hour
Hora depois 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
Valor positivo se o horário de verão é aplicado; 0 se o horário de verão não for aplicado; valor negativo se o status do horário de verão é desconhecido. Se a variável de ambiente de TZ estiver definido, a biblioteca de tempo de execução C assumirá as regras apropriadas aos Estados Unidos para implementar o cálculo de horário de verão (DST).

Comentários

A função de localtime converte uma hora armazenados como um valor de time_t e armazena o resultado em uma estrutura de tipo tm. O valor timer de long representa os segundos decorridos desde meia-noite (00:00: 00), o 1º de janeiro de 1970, UTC. Esse valor é obtido em geral da função de time .

As versões de 32 bits e de 64 bits de gmtime, de mktime, de mkgmtime, e de localtime usam uma única estrutura de tm pelo thread para a conversão. Cada chamada para uma dessas rotinas destrói o resultado da chamada anterior.

localtime corrige para o fuso horário local se o usuário define primeiramente a variável de ambiente global TZ. Quando TZ for definido, os outros três variáveis de ambiente (_timezone, _daylight, e _tzname) serão definidos automaticamente também. Se a variável de TZ não for definido, localtime tenta usar as informações de fuso horário especificada no aplicativo de data/hora no painel de controle. Se essas informações não pode ser obtida, PST8PDT, que significa o fuso horário do pacífico, será usado por padrão. Consulte _tzset para obter uma descrição dessas variáveis. TZ é uma extensão da Microsoft e não uma parte da definição do padrão ANSI de localtime.

Dica

O ambiente de destino deve tentar determinar se o horário de verão é aplicado.

Essas funções validam seus parâmetros. Se timer for um ponteiro nulo ou se o valor do temporizador for negativo, essas funções chamarão um manipulador de parâmetro inválido, como descrito em Validação do parâmetro. Se a execução puder continuar, as funções retornarão NULL e definirão errno como EINVAL.

Requisitos

Rotina	Cabeçalho necessário
localtime	<time.h>
_localtime32	<time.h>
_localtime64	<time.h>

Para informações adicionais de compatibilidade, consulte Compatibilidade na Introdução.

Exemplo

// crt_localtime.cpp
// compile with: /W3
/* This program uses _time64 to get the current time 
 * and then uses localtime64() to convert this time to a structure 
 * representing the local time. The program converts the result 
 * from a 24-hour clock to a 12-hour clock and determines the 
 * proper extension (AM or PM).
 */

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

int main( void )
{
        struct tm *newtime;
        char am_pm[] = "AM";
        __time64_t long_time;

        _time64( &long_time );           // Get time as 64-bit integer.
                                         // Convert to local time.
        newtime = _localtime64( &long_time ); // C4996
        // Note: _localtime64 deprecated; consider _localetime64_s

        if( newtime->tm_hour > 12 )        // Set up extension.
                strcpy_s( am_pm, sizeof(am_pm), "PM" );
        if( newtime->tm_hour > 12 )        // Convert from 24-hour
                newtime->tm_hour -= 12;    //   to 12-hour clock.
        if( newtime->tm_hour == 0 )        // Set hour to 12 if midnight.
                newtime->tm_hour = 12;

        char buff[30];
        asctime_s( buff, sizeof(buff), newtime );
        printf( "%.19s %s\n", buff, am_pm );
}