localtime, _localtime32, _localtime64

Converte um valor temporal e o corrige de acordo com o fuso horário local. Versões mais seguras dessas funções estão disponíveis; confira localtime_s, _localtime32_s, _localtime64_s.

Sintaxe

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

Parâmetros

sourceTime
Ponteiro para a hora armazenada.

Retornar valor

Retornar um ponteiro para o resultado da estrutura ou NULL se a data passada para a função for:

• Antes da meia-noite de 1º de janeiro de 1970.

• Após 03:14:07 de 19 de janeiro de 2038, UTC (usando _time32 e time32_t).

• Após 23:59:59 de 31 de dezembro de 3000, UTC (usando _time64 e __time64_t).

_localtime64, 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 _localtime32 representa datas até 23:59:59 de 18 de janeiro de 2038, no UTC.

localtime é uma função embutida que é avaliada como _localtime64 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 causas localtime a avaliar para _localtime32. Não recomendamos _USE_32BIT_TIME_T, porque seu aplicativo pode falhar após 18 de janeiro de 2038 e não é permitido em plataformas de 64 bits.

Os campos do tipo de estrutura tm armazenam seguintes valores, cada um dos quais é um int:

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	Valor positivo se o horário de verão estiver em vigor; 0 se o horário de verão não estiver em vigor; Valor negativo se o status do horário de verão for desconhecido.

Se a variável de ambiente TZ estiver definida, a biblioteca em tempo de execução C presume que as regras dos Estados Unidos serão usadas para implementar o cálculo do DST (horário de verão).

Comentários

A função localtime converte uma hora armazenada como um valor time_t e armazena o resultado em uma estrutura do tipo tm. O valor longsourceTime representa os segundos passados desde a meia-noite (00:00:00) de 1º de janeiro de 1970, no UTC. Este valor é frequentemente obtido a partir da time função.

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

localtime corrige o fuso horário local se o usuário definir a variável de ambiente global TZ primeiro. Ao definir TZ, três outras variáveis de ambiente (_timezone, _daylight e _tzname) também serão definidas automaticamente. Se a TZ variável não estiver definida, localtime tentará usar as informações de fuso horário especificadas no aplicativo Data/Hora no Painel de Controle. Se essas informações não puderem ser obtidas, PST8PDT, que significa o fuso horário do Pacífico, será usado por padrão. Confira _tzset para obter uma descrição dessas variáveis. TZ é uma extensão da Microsoft e não faz parte da definição padrão ANSI de localtime.

Observação

O ambiente de destino deve tentar determinar se o horário de verão está em vigor.

Essas funções validam seus parâmetros. Se sourceTime for um ponteiro nulo ou se o sourceTime valor for negativo, essas funções invocarão um manipulador de parâmetros inválido, conforme descrito em Validação de parâmetro. Se a execução tiver permissão para continuar, essas funções retornarão NULL e definirão errno como EINVAL.

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

Requisitos

Rotina	Cabeçalho C necessário	Cabeçalho C++ necessário
localtime, _localtime32, _localtime64	<time.h>	<ctime> ou <time.h>

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

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

Tue Feb 12 10:05:58 AM

Confira também

Gerenciamento de tempo
asctime, _wasctime
ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64
_ftime, _ftime32, _ftime64
gmtime, _gmtime32, _gmtime64
localtime_s, _localtime32_s, _localtime64_s
time, _time32, _time64
_tzset