asctime_s，_wasctime_s

将 tm 时间结构转换为字符串。 这些函数的版本是 asctime、_wasctime，具有安全性增强功能，如 CRT 中的安全功能中所述。

语法

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 对象的指针。

返回值

如果成功，则返回 0。 如果失败，则调用无效的参数处理程序，如参数验证中所述。 如果允许继续执行，则返回值为错误代码。 错误代码是在 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 函数将存储为结构的时间转换为字符串。 通常通过调用 gmtime 或 localtime 获取 tmSource 值。 这两个函数都可以用于填充 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；1 月 = 0）
tm_sec	整分后的秒数 (0-59)
tm_wday	每周的某一日（0-6；星期天 = 0）
tm_yday	一年的某一天（0-365；1 月 1 日 = 0）
tm_year	年（当前年份减去 1900）

转换的字符串同时根据本地时区设置进行调整。 有关配置本地时间的信息，请参阅 time、_time32、_time64、_ftime、_ftime32、_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++ 中，通过模板重载简化这些函数的使用；重载可以自动推导出缓冲区长度，不再需要指定大小参数。 有关详细信息，请参阅安全模板重载。

要求

例程	必需的标头
asctime_s	<time.h>
_wasctime_s	<time.h> 或 <wchar.h>

安全性

如果缓冲区指针不是 NULL，并且指针不指向有效的缓冲区，函数将覆盖该位置处的全部内容。 此错误还可能导致访问冲突。

如果传入的大小参数大于缓冲区的实际大小，则可能会发生缓冲区溢出。

示例

此程序以长整型 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、_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