Поделиться через

asctime_s, _wasctime_s

  • Статья

Преобразуют структуру времени tm в символьную строку. Эти функции — это версии с улучшениями безопасности, _wasctimeкак описано в функциях безопасности в CRT.asctime

Синтаксис

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

Параметры

buffer
Указатель на буфер для хранения результата строки символов. Эта функция принимает указатель на допустимое расположение в памяти, размер которого указан в numberOfElements.

numberOfElements
Размер буфера, используемого для хранения результата.

tmSource
Структура даты/времени. Эта функция принимает указатель на допустимый объект struct tm.

Возвращаемое значение

Нуль при успешном завершении. Если произошел сбой, вызывается обработчик недопустимых параметров, как описано в разделе проверки параметров. Если выполнение может быть продолжено, функция возвращает код ошибки. Коды ошибок определенны в ERRNO.H. Дополнительные сведения см. в разделе errno констант. Фактические коды ошибок, возвращаемые для каждого условия ошибки, приведены в следующей таблице.

Условия ошибок

buffer numberOfElements tmSource Возврат Значение в buffer
NULL Любой Любой EINVAL Не изменено
Не NULL (указывает на допустимый адрес в памяти) 0 Любое EINVAL Не изменено
Не NULL 0<numberOfElements< 26 Любое EINVAL Пустая строка
Не NULL >= 26 NULL EINVAL Пустая строка
Не NULL >= 26 Недопустимая структура времени или компоненты времени выходят за пределы допустимого диапазона EINVAL Пустая строка

Примечание.

Условия ошибки для функции wasctime_s аналогичны таковым для функции asctime_s, но ограничение размера измеряется в словах.

Замечания

Функция asctime преобразует время, хранящееся в виде структуры, в символьную строку. Значение tmSource обычно получается из вызова gmtime или localtime. Обе функции могут использоваться для заполнения структуры tm, как определено в файле TIME.H.

Член timeptr Значение
tm_hour Часы с полуночи (0-23)
tm_isdst Положительное значение, если летнее время действует; 0, если летнее время не действует; отрицательно, если состояние летнего времени неизвестно. Библиотека времени выполнения C принимает правила США для реализации проверки на летнее время (DST).
tm_mday День месяца (1-31)
tm_min Минуты после часа (0-59)
tm_mon Месяц (0-11; Январь = 0)
tm_sec Секунды после минуты (0-59)
tm_wday День недели (0-6; Воскресенье = 0)
tm_yday День года (0-365; 1 января = 0)
tm_year Год (текущий год минус 1900)

Преобразованная символьная строка также настраивается согласно параметрам местного часового пояса. Сведения о настройке локального времени см. в функциях time, _time32,_ftime32_time64_ftime, , _ftime64а localtime_sтакже _localtime32_s_localtime64_s о функциях. Сведения об определении среды часового пояса и глобальных переменных см. в статье _tzset.

Итоговая строка, полученная с помощью asctime_s, содержит ровно 26 символов и имеет вид Wed Jan 2 02:03:55 1980\n\0. Время в 24-часовом формате. Все поля имеют постоянную ширину. Символ новой строки и нуль-символ занимают две последние позиции строки. Значение, переданное как numberOfElements должно быть по крайней мере таким размером. Если это меньше, EINVALвозвращается код ошибки.

_wasctime_s — это версия функции asctime_s для расширенных символов. Поведение_wasctime_s и asctime_s идентично в противном случае.

Версии библиотек отладки этих функций сначала заполняют буфер 0xFE. Чтобы отключить это поведение, используйте _CrtSetDebugFillThreshold.

По умолчанию глобальное состояние этой функции ограничивается приложением. Чтобы изменить это поведение, см . статью "Глобальное состояние" в CRT.

Сопоставление подпрограмм универсального текста

Подпрограмма TCHAR.H _UNICODE и _MBCS не определен _MBCS Определенные _UNICODE Определенные
_tasctime_s asctime_s asctime_s _wasctime_s

В C++ использование этих функций упрощено шаблонными перегрузками; перегрузки могут определить длину буфера автоматически, устраняя необходимость указывать аргумент size. Дополнительные сведения см. в разделе "Безопасные перегрузки шаблонов".

Требования

Маршрут Обязательный заголовок
asctime_s <time.h>
_wasctime_s <time.h> или <wchar.h>

Безопасность

Если указатель буфера не NULL указан, а указатель не указывает на допустимый буфер, функция перезаписывает все, что находится в расположении. Эта ошибка также может привести к нарушению доступа.

Если переданный аргумент size превышает фактический размер буфера, может возникать ошибка переполнения буфера.

Пример

Эта программа помещает системное время в длинное целое число aclock, преобразует его в структуру newtime, а затем преобразует его в строковую asctime_s форму для вывода с помощью функции.

// 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

См. также

Управление временем
ctime_s, , _ctime32_s_wctime_s_ctime64_s_wctime32_s,_wctime64_s
_ftime, , _ftime32_ftime64
gmtime_s, , _gmtime32_s_gmtime64_s
localtime_s, , _localtime32_s_localtime64_s
time, , _time32_time64
_tzset