asctime_s, _wasctime_s

Artigo
02/25/2013

Converter um tm estrutura para uma seqüência de caracteres de tempo.Essas funções são as versões do asctime, _wasctime com aprimoramentos de segurança, conforme descrito em Recursos de segurança no CRT.

errno_t asctime_s( 
   char* buffer,
   size_t numberOfElements,
   const struct tm *_tm 
);
errno_t _wasctime_s( 
   wchar_t* buffer,
   size_t numberOfElements
   const struct tm *_tm 
);
template <size_t size>
errno_t asctime_s( 
   char (&buffer)[size],
   const struct tm *_tm 
); // C++ only
template <size_t size>
errno_t _wasctime_s( 
   wchar_t (&buffer)[size],
   const struct tm *_tm 
); // C++ only

Parâmetros

buffer
[out] Um ponteiro para um buffer para armazenar o resultado da seqüência de caracteres.Essa função assume um ponteiro para um local de memória válido com um tamanho especificado por numberOfElements.
numberOfElements
[in] O tamanho do buffer usado para armazenar o resultado.
_tm
[in] Estrutura de hora/data.Essa função assume um ponteiro para um assembly válido structtm objeto.

Valor de retorno

Zero se for bem sucedida.Se houver uma falha, 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, o valor de retorno é um código de erro.Códigos de erro são definidos no ERRNO.H.Para obter mais informações, consulte errno constantes.Os códigos de erro real retornados para cada condição de erro são mostrados na tabela a seguir.

Condições de erro

buffer	numberOfElements	tm	Return	O valorbuffer
NULL	Qualquer	Qualquer	EINVAL	Não modificado
NãoNULL (aponta para memória válido)	0	Qualquer	EINVAL	Não modificado
NãoNULL	0 < tamanho < 26	Qualquer	EINVAL	Seqüência de caracteres vazia
NãoNULL	> = 26	NULL	EINVAL	Seqüência de caracteres vazia
NãoNULL	> = 26	Estrutura de horário inválido ou valores fora da faixa para componentes de tempo	EINVAL	Seqüência de caracteres vazia

Observação
Condições de erro para wasctime_s são semelhantes aos asctime_s com a exceção de que o limite de tamanho é medido em palavras.

Comentários

O asctime função converte um horário armazenado como uma estrutura para uma seqüência de caracteres.O _tm valor geralmente é obtido de uma chamada para gmtime ou localtime.Ambas as funções podem ser usadas para preencher um tm estrutura, conforme definido no momento.H.

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

A seqüência de caracteres convertidas também é ajustada de acordo com as configurações de fuso horário local.Consulte o tempo, _time32, _time64, _ftime, _ftime32, _ftime64, e localtime_s, _localtime32_s, _localtime64_s funções para obter informações sobre como configurar a hora local e o _tzset a função para obter informações sobre como definir o ambiente de fuso horário e variáveis globais.

O resultado da seqüência de caracteres produzido por asctime_s contém exatamente 26 caracteres e tem a forma Wed Jan 02 02:03:55 1980\n\0.É usado um relógio de 24 horas.Todos os campos tem uma largura de constante.O caractere de nova linha e o caractere nulo ocupam as duas últimas posições da seqüência de caracteres.O valor passado como o segundo parâmetro deve ser pelo menos nesse grande.Se for menos, um código de erro, EINVAL, será retornado.

_wasctime_sé uma versão de caractere largo de asctime_s._wasctime_se asctime_s tenham comportamento idêntico caso contrário.

Mapeamento de rotina de texto genérico

TCHAR.Rotina H	_ Unicode & _ MBCS do arquivo não definido	_ MBCS do arquivo definido	_ Unicode definido
_tasctime_s	asctime_s	asctime_s	_wasctime_s

No C++, a utilização dessas funções é simplificado pela sobrecargas do modelo; os métodos sobrecarregados podem inferir comprimento do buffer automaticamente, eliminando a necessidade de especificar um argumento de tamanho.Para obter mais informações, consulte Proteger Overloads de modelo.

Requisitos

Rotina	Cabeçalho necessário
asctime_s	<time.h>
_wasctime_s	<time.h> ou <wchar.h>

Segurança

Se o ponteiro de buffer não é NULL e o ponteiro não aponta para um buffer válido, a função irá sobrescrever tudo o que está no local.Isso também pode resultar em uma violação de acesso.

A de saturação de buffer pode ocorrer se o argumento de tamanho passado for maior que o tamanho real do buffer.

Exemplo

Este programa coloca a hora do sistema no inteiro longo aclock, converte-o para a estrutura de newtime e o converte em forma de seqüência de saída, usando o asctime_s função.

// crt_asctime_s.c
#include <time.h>
#include <stdio.h>

struct tm newtime;
__time32_t aclock;

int main( void )
{
   char buffer[32];
   errno_t errNum;
   _time32( &aclock );   // Get time in seconds.
   _localtime32_s( &newtime, &aclock );   // Convert time to struct tm form.

   // Print local time as a string.

   errNum = asctime_s(buffer, 32, &newtime);
   if (errNum)
   {
       printf("Error code: %d", (int)errNum);
       return 1;
   }
   printf( "Current date and time: %s", buffer );
   return 0;
}