Partilhar via


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