asctime_s, _wasctime_s

Artigo
08/25/2010

Converter um tm estrutura de time a uma seqüência de caractere. Essas funções são versões de asctime, _wasctime com aprimoramentos de segurança sistema autônomo descrito em Aprimoramentos 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 caractere.Essa função assume um ponteiro para um local de memória válido com um dimensionar especificado por numberOfElements.
numberOfElements
[in] O dimensionar do buffer usado para armazenar o resultado.
_tm
[in] Data/time estrutura.This function assumes a pointer to a valid structtm object.

Valor de retorno

Zero se for bem-sucedido.Se houver uma falha, o manipulador de parâmetro inválido é chamado, conforme descrito em Validação de parâmetro. Se a execução for permitida para continuar, o valor retornado é um código de erro.Códigos de erro estão definidos no ERRNO.H.For more information, see Constantes errno.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	Valor em buffer
NULL	Qualquer	Qualquer	EINVAL	Não modificado
NotNULL (points to valid memory)	0	Qualquer	EINVAL	Não modificado
Not NULL	0 < dimensionar < 26	Qualquer	EINVAL	Seqüência de caracteres vazia
Not NULL	>= 26	NULL	EINVAL	Seqüência de caracteres vazia
Not NULL	>= 26	Estrutura de time inválido ou está fora do intervalo valores para componentes de time	EINVAL	Seqüência de caracteres vazia

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

Comentários

The asctime função converte uma time armazenada sistema autônomo uma estrutura para uma seqüência de caractere. The _tm valor geralmente é obtido de uma telefonar para gmtime ou localtime. Ambas sistema autônomo funções podem ser usadas para preencher um tm estrutura, conforme definido no TIME.H.

membro timeptr	Valor
tm_hour	Horas desde a meia-noite (0 – 23)
tm_isdst	Positivo se o time de economia de horário de verão estiver em vigor; 0 se a time de verão não em vigor; negativo se status do horário de verão for desconhecido.A biblioteca de time 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 hora (0 – 59)
tm_mon	Mês (0–11; janeiro = 0)
tm_sec	Segundos após minuto (0 – 59)
tm_wday	Dia da semana (0 a 6; domingo = 0)
tm_yday	Dia do ano (0–365; 0 = 1 º de janeiro)
tm_year	Ano (ano corrente menos 1900)

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

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

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

Mapeamento de rotina de texto genérica

Rotina TCHAR.H	_UNICODE & _MBCS não definido	_MBCS definido	_UNICODE definido
_tasctime_s	asctime_s	asctime_s	_wasctime_s

No C++, usando essas funções é simplificado pela sobrecargas de modelo; sobrecargas de podem inferir comprimento do buffer automaticamente, eliminando a necessidade de especificar um argumento de dimensionar.For more information, see 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 substituirá qualquer item que está no local. Isso também pode resultar em uma violação de acesso.

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

Exemplo

Este programa coloca a time do sistema o long inteiro aclock, converte-o para a estrutura newtime e a converte ao formulário de cadeia de caracteres para 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;
}

Current date and time: Wed May 14 15:30:17 2003