%>

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 函数将存储为结构的时间转换为字符串。 通常通过调用 gmtimelocaltime 获取 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_ftime64localtime_s_localtime32_s_localtime64_s 函数。 有关定义时区环境和全局变量的信息,请参阅 _tzset

asctime_s 生成的字符串结果正好包含 26 个字符,格式为 Wed Jan 2 02:03:55 1980\n\0。 使用 24 小时制。 所有字段都具有固定宽度。 换行符和空字符占据字符串的最后两个位置。 作为 numberOfElements 传入的值应至少为此大小。 如果是更小的值,将返回错误代码 EINVAL

_wasctime_sasctime_s 的宽字符版本。 除此以外,_wasctime_sasctime_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

另请参阅

工时管理

.- .
.- .
.- .
.- .
_tzset