localtime_s, _localtime32_s, _localtime64_s

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 do , , com aprimoramentos de segurança,_localtime32_localtime64conforme descrito em Recursos de localtimesegurança na 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.

Retornar valor

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	Retornar valor	Valor em tmDest	Invoca um manipulador de parâmetro inválido
NULL	qualquer	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 duas primeiras condições de erro invocam o 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 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. Este valor é frequentemente obtido a partir 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, quais causas localtime_s avaliar para _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, consulte Estado global na 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