Compartilhar via

localtime_s, _localtime32_s, _localtime64_s

  • Artigo

Converte um valor temporal time_t em uma estrutura tm e o corrige de acordo com o fuso horário local. Essas funções são versões de , , _localtime64com aprimoramentos delocaltime segurança, _localtime32conforme descrito em Recursos de segurança no CRT.

Sintaxe

errno_t localtime_s(
   struct tm* const tmDest,
   time_t const* const sourceTime
);
errno_t _localtime32_s(
   struct tm* tmDest,
   __time32_t const* sourceTime
);
errno_t _localtime64_s(
   struct tm* tmDest,
   __time64_t const* sourceTime
);

Parâmetros

tmDest
Ponteiro para a estrutura de hora a ser preenchida.

sourceTime
Ponteiro para a hora armazenada.

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 no Errno.h. Para ver uma lista desses erros, confira errno.

Condições de erro

tmDest sourceTime Valor retornado Valor em tmDest Invoca um manipulador de parâmetro inválido
NULL any EINVAL Não modificado Sim
Não é NULL (aponta para a memória válida) NULL EINVAL Todos os campos definidos como -1 Sim
Não é NULL (aponta para a memória válida) menor que 0 ou maior que _MAX__TIME64_T EINVAL Todos os campos definidos como -1 Não

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 localtime_s converte uma hora armazenada como um valor time_t e armazena o resultado em uma estrutura do tipo tm. O valor time_tsourceTime representa os segundos passados desde a meia-noite (00:00:00) de 1º de janeiro de 1970, no UTC. Esse valor geralmente é obtido da time função.

localtime_s 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_s 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.

_localtime64_s, que usa a estrutura __time64_t, permite que as datas sejam expressas até 23:59:59 de 18 de janeiro de 3001, no UTC, enquanto _localtime32_s representa datas até 23:59:59 de 18 de janeiro de 2038, no UTC.

localtime_s é uma função embutida que é avaliada como _localtime64_s e time_t é equivalente a __time64_t. Se você precisar forçar o compilador a interpretar time_t como o antigo de 32 bits time_t, você pode definir _USE_32BIT_TIME_T, que faz com que a localtime_s avaliação seja _localtime32_s. 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 os valores a seguir, 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).

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
localtime_s, _localtime32_s, _localtime64_s <time.h> <ctime> ou <time.h>

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

Exemplo

// crt_localtime_s.c
// This program uses _time64 to get the current time
// and then uses _localtime64_s() 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;
    char timebuf[26];
    errno_t err;

    // Get time as 64-bit integer.
    _time64( &long_time );
    // Convert to local time.
    err = _localtime64_s( &newtime, &long_time );
    if (err)
    {
        printf("Invalid argument to _localtime64_s.");
        exit(1);
    }
    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;

    // Convert to an ASCII representation.
    err = asctime_s(timebuf, 26, &newtime);
    if (err)
    {
        printf("Invalid argument to asctime_s.");
        exit(1);
    }
    printf( "%.19s %s\n", timebuf, am_pm );
}

Fri Apr 25 01:19:27 PM

Confira também

Gerenciamento de tempo
asctime_s, _wasctime_s
ctime, _ctime32, _ctime64, _wctime, _wctime32, , _wctime64
_ftime, _ftime32, _ftime64
gmtime_s, _gmtime32_s, _gmtime64_s
localtime, _localtime32, _localtime64
time, _time32, _time64
_tzset