localtime_s, _localtime32_s, _localtime64_s

Artigo
02/25/2013

Converte um valor de tempo e corrige o fuso horário local.Estas são as versões do localtime, _localtime32, _localtime64 com aprimoramentos de segurança, conforme descrito em Recursos de segurança no CRT.

errno_t localtime_s(
   struct tm* _tm,
   const time_t *time 
);
errno_t _localtime32_s(
   struct tm* _tm,
   const time32_t *time 
);
errno_t _localtime64_s(
   struct tm* _tm,
   const _time64_t *time 
);

Parâmetros

_tm
Ponteiro para a estrutura de tempo para ser preenchido.
time
Ponteiro para o tempo armazenado.

Valor de retorno

Zero se for bem sucedida.O valor de retorno é um código de erro, se houver uma falha.Códigos de erro são definidos no errno. h.Para obter uma lista desses erros, consulte errno.

Condições de erro

_tm	time	Valor de Retorno	O valor_tm	Chama o manipulador de parâmetro inválido
NULL	any	EINVAL	Não modificado	Sim
Não NULL (aponta para memória válido)	NULL	EINVAL	Todos os campos definidos como -1	Sim
Não NULL (aponta para memória válido)	menor que 0 ou maior que_MAX__TIME64_T	EINVAL	Todos os campos definidos como -1	Não

No caso das condições de erro de dois primeira, o manipulador de parâmetro inválido é invocado, conforme descrito em Validação de parâmetro.Se a execução terá permissão para continuar, essas funções definir errno para EINVAL e retornar EINVAL.

Comentários

O _localtime32_s função converte um horário armazenado como um time_t valor e armazena o resultado em uma estrutura do tipo tm.O long valor timer representa os segundos passados desde meia-noite (00: 00), 1 de janeiro de 1970, UTC.Esse valor normalmente é obtido a partir do time função.

_localtime32_scorrige o fuso horário local se o usuário primeiro definir a variável de ambiente global TZ.Quando TZ for definido, três outras variáveis de ambiente (_timezone, _daylight, e _tzname) são definidas automaticamente também.Se a TZ variável não estiver definido, localtime32_s tenta usar as informações de fuso horário especificadas no aplicativo de data/hora no painel de controle.Se essa informação não pode ser obtida, PST8PDT, o que significa o fuso horário do Pacífico, é usado por padrão.Consulte _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 __time64_t estruturar, permite que as datas a ser expressa até a 23: 59: 59, 31 de dezembro de 3000, a hora universal coordenada (UTC), enquanto _localtime32_s representa as datas até 03: 14: 07 em 19 de janeiro de 2038, UTC.

localtime_sé uma função in-line que é avaliada como _localtime64_s, e time_t é equivalente a __time64_t.Se você precisar forçar o compilador para interpretar time_t como o antigo 32-bit time_t, você pode definir _USE_32BIT_TIME_T.Fazendo isso fará com que localtime_s a ser avaliada como _localtime32_s.Isso não é recomendado porque seu aplicativo pode falhar após 19 de janeiro de 2038, e não é permitido em plataformas de 64 bits.

Os campos do tipo structure tm armazenar os valores a seguir, cada um deles é um int.

tm_sec
Segundos após minuto (0 – 59).
tm_min
Minutos após hora (0 – 59).
tm_hour
Horas após a meia-noite (0 – 23).
tm_mday
Dia do mês (1 – 31).
tm_mon
Mês (0 – 11; Janeiro = 0).
tm_year
Ano (ano atual menos 1900).
tm_wday
Dia da semana (0 – 6; Domingo = 0).
tm_yday
Dia do ano (0 – 365 dias por ano; 1º De janeiro = 0).
tm_isdst
Valor positivo se o horário de verão está em vigor; 0 se o horário de verão não está em vigor. valor negativo se o status do horário de verão é desconhecido.Se a TZ a variável de ambiente é definida, a biblioteca de tempo de execução c assume regras apropriadas para os Estados Unidos para implementar o cálculo do horário de verão (DST).

Requisitos

Rotina	Cabeçalho necessário
localtime_s	<time.h>
_localtime32_s	<time.h>
_localtime64_s	<time.h>

Para obter mais informações de compatibilidade, consulte compatibilidade na introdução.

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