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 aclock
longo , traduz-o na estrutura newtime
e, 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
Comentários
https://aka.ms/ContentUserFeedback.
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja:Submeter e ver comentários