asctime_s, _wasctime_s

Converter uma estrutura de hora tm para uma cadeia de caracteres. Estas funções são versões de asctime, _wasctime com aprimoramentos de segurança, conforme descrito em Recursos de segurança no CRT.

Sintaxe

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

Parâmetros

buffer
Um ponteiro para um buffer para armazenar o resultado da cadeia de caracteres. Essa função assume um ponteiro para um local de memória válido com um tamanho especificado por numberOfElements.

numberOfElements
O tamanho do buffer usado para armazenar o resultado.

tmSource
Estrutura de hora/data. Essa função assume um ponteiro para um objeto struct tm válido.

Valor retornado

Zero se for bem-sucedido. Se houver uma falha, o manipulador de parâmetro inválido será invocado, conforme descrito em Validação de parâmetro. Se a execução puder continuar, o valor retornado será um código de erro. Códigos de erro são definidos em ERRNO.H. Para obter mais informações, consulte errno constantes. Os códigos de erro reais retornados para cada condição de erro são mostrados na tabela a seguir.

Condições de erro

buffer	numberOfElements	tmSource	Return	Valor em buffer
NULL	Qualquer	Qualquer	EINVAL	Não modificado
Não é NULL (aponta para a memória válida)	0	Qualquer	EINVAL	Não modificado
Não é NULL	<numberOfElements< 0 26	Qualquer	EINVAL	Cadeia de caracteres vazia
Não é NULL	>= 26	NULL	EINVAL	Cadeia de caracteres vazia
Não é NULL	>= 26	Estrutura de hora inválida ou valores fora do intervalo para os componentes da hora	EINVAL	Cadeia de caracteres vazia

Observação

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

Comentários

A função asctime converte uma hora armazenada como uma estrutura para uma cadeia de caracteres. O tmSource valor normalmente é obtido de uma chamada para gmtime ou localtime. Ambas as funções podem ser usadas para preencher uma estrutura tm, conforme definido em TIME.H.

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

A cadeia de caracteres convertida também é ajustada de acordo com as configurações de fuso horário local. Para obter informações sobre como configurar a hora local, consulte as funções , _time32, _time64, _ftime, _ftime32, _ftime64, elocaltime_s , _localtime32_s, _localtime64_s .time Para obter informações sobre como definir o ambiente de fuso horário e as variáveis globais, consulte _tzset.

O resultado da cadeia de caracteres produzido por asctime_s contém exatamente 26 caracteres e tem o formato Wed Jan 2 02:03:55 1980\n\0. Um relógio de 24 horas é usado. Todos os campos têm uma largura constante. O caractere de nova linha e o caractere nulo ocupam as duas últimas posições da cadeia de caracteres. O valor passado como numberOfElements deve ser pelo menos esse tamanho. Se for menor, um código de erro, EINVAL, será retornado.

_wasctime_s é uma versão de caractere largo de asctime_s. Caso contrário, _wasctime_s e asctime_s se comportam de forma idêntica.

As versões de biblioteca de depuração dessas funções preenchem o buffer com 0xFE. Para desabilitar esse comportamento, use _CrtSetDebugFillThreshold.

Por padrão, o estado global dessa função tem como escopo o aplicativo. Para alterar esse comportamento, confira Estado global no CRT.

Mapeamento de rotina de texto genérico

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

No C++, o uso dessas funções é simplificado por sobrecargas de modelo. As sobrecargas podem inferir automaticamente o tamanho do buffer, eliminando a necessidade de especificar um argumento de tamanho. Para obter mais informações, consulte Sobrecargas de modelo seguras.

Requisitos

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

Segurança

Se o ponteiro do buffer não NULL estiver e o ponteiro não apontar para um buffer válido, a função substituirá o que estiver no local. Esse erro também pode resultar em uma violação de acesso.

O estouro de buffer poderá 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 aclocklongo , traduz-o na estrutura newtimee, em seguida, converte-o em forma de string para saída, usando a 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

Confira também

Gerenciamento de tempo
ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, , _wctime64_s
_ftime, _ftime32, _ftime64
gmtime_s, _gmtime32_s, _gmtime64_s
localtime_s, _localtime32_s, _localtime64_s
time, _time32, _time64
_tzset