ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s

将时间值转换为字符串，并调整本地时区设置。 这些函数的版本是 ctime、_ctime64、_wctime、_wctime64，具有安全性增强功能，如 CRT 中的安全功能中所述。

语法

errno_t ctime_s(
   char* buffer,
   size_t numberOfElements,
   const time_t *sourceTime
);
errno_t _ctime32_s(
   char* buffer,
   size_t numberOfElements,
   const __time32_t *sourceTime
);
errno_t _ctime64_s(
   char* buffer,
   size_t numberOfElements,
   const __time64_t *sourceTime )
;
errno_t _wctime_s(
   wchar_t* buffer,
   size_t numberOfElements,
   const time_t *sourceTime
);
errno_t _wctime32_s(
   wchar_t* buffer,
   size_t numberOfElements,
   const __time32_t *sourceTime
);
errno_t _wctime64_s(
   wchar_t* buffer,
   size_t numberOfElements,
   const __time64_t *sourceTime
);

template <size_t size>
errno_t _ctime32_s(
   char (&buffer)[size],
   const __time32_t *sourceTime
); // C++ only
template <size_t size>
errno_t _ctime64_s(
   char (&buffer)[size],
   const __time64_t *sourceTime
); // C++ only
template <size_t size>
errno_t _wctime32_s(
   wchar_t (&buffer)[size],
   const __time32_t *sourceTime
); // C++ only
template <size_t size>
errno_t _wctime64_s(
   wchar_t (&buffer)[size],
   const __time64_t *sourceTime
); // C++ only

参数

buffer
必须足以容纳 26 个字符。 在以下情况下，为指向字符串结果的指针，或者为 NULL：

• sourceTime 表示 1970 年 1 月 1 日午夜前的日期（UTC 时间）。

• 如果使用 _ctime32_s 或 _wctime32_s，且 sourceTime 表示 2038 年 1 月 18 日 23:59:59 后的日期（UTC 时间）。

• 如果使用 _ctime64_s 或 _wctime64_s，且 sourceTime 表示 3000 年 12 月 31 日 23:59:59 后的日期（UTC 时间）。

• 如果使用 _ctime_s 或 _wctime_s，这些函数就成为之前的函数的包装器。 请参阅“备注”部分。

numberOfElements
缓冲区的大小。

sourceTime
指向存储时间的指针。

返回值

如果成功，则返回 0。 如果由于无效参数导致失败，则调用无效的参数处理程序，如参数验证中所述。 如果允许执行继续，则返回错误代码。 在 ERRNO.H 中定义了错误代码；有关这些错误的列表，请参阅 errno。 针对每个错误条件而引发的实际错误代码如下表所示。

错误条件

buffer	numberOfElements	sourceTime	返回值	buffer 中的值
NULL	任意	any	EINVAL	未修改
非 NULL（指向有效内存）	0	any	EINVAL	未修改
非 NULL	大于 0 且小于 26	任意	EINVAL	空字符串
非 NULL	>= 26	Null	EINVAL	空字符串
非 NULL	>= 26	< 0	EINVAL	空字符串

注解

ctime_s 函数将存储为 time_t 结构的时间值转换为字符串。 通常情况下，通过对 time 的调用获取 sourceTime 值，它返回自协调世界时 (UTC) 1970 年 1 月 1 日午夜 (00:00:00) 以来经过的秒数。 返回值字符串正好包含 26 个字符，且格式为：

Wed Jan 2 02:03:55 1980\n\0

使用 24 小时制。 所有字段都具有固定宽度。 新换行符 ('\n') 和空字符 ('\0') 占据字符串的最后两个位置。

转换的字符串同时根据本地时区设置进行调整。 若要了解如何配置本地时间，请参阅 time、_ftime 和 localtime 函数。 若要详细了解如何定义时区环境和全局变量，请参阅 _tzset 函数。

_wctime32_s 和 _wctime64_s 是 _ctime32_s 和 _ctime64_s 的宽字符版本；返回指向宽字符串的指针。 否则，_ctime64_s、_wctime32_s 和 _wctime64_s 的行为与 _ctime32_s 完全相同。

ctime_s 是计算出 _ctime64_s 的内联函数，且 time_t 等同于 __time64_t。 如果需要强制编译器将 time_t 解释为旧的 32 位 time_t，你可以定义 _USE_32BIT_TIME_T。 此宏导致 ctime_s 计算结果为 _ctime32_s。 不建议这样做，因为应用程序可能会在 2038 年 1 月 18 日后失效；且在 64 位平台上不允许使用它。

在 C++ 中，通过模板重载简化这些函数的使用；重载可以自动推导出缓冲区长度，不再需要指定大小参数。 有关详细信息，请参阅安全模板重载。

这些函数的调试库版本首先用 0xFE 填充缓冲区。 若要禁用此行为，请使用 _CrtSetDebugFillThreshold。

默认情况下，此函数的全局状态范围限定为应用程序。 若要更改此行为，请参阅 CRT 中的全局状态。

一般文本例程映射

TCHAR.H 例程	_UNICODE 和 _MBCS 未定义	_MBCS 已定义	_UNICODE 已定义
_tctime_s	ctime_s	ctime_s	_wctime_s
_tctime32_s	_ctime32_s	_ctime32_s	_wctime32_s
_tctime64_s	_ctime64_s	_ctime64_s	_wctime64_s

要求

例程	必需的标头
ctime_s, _ctime32_s, _ctime64_s	<time.h>
_wctime_s, _wctime32_s, _wctime64_s	<time.h> 或 <wchar.h>

有关兼容性的详细信息，请参阅 兼容性。

库

C 运行时库的所有版本。

示例

// crt_wctime_s.c
// This program gets the current
// time in time_t form and then uses _wctime_s to
// display the time in string form.

#include <time.h>
#include <stdio.h>

#define SIZE 26

int main( void )
{
   time_t ltime;
   wchar_t buf[SIZE];
   errno_t err;

   time( &ltime );

   err = _wctime_s( buf, SIZE, &ltime );
   if (err != 0)
   {
      printf("Invalid Arguments for _wctime_s. Error Code: %d\n", err);
   }
   wprintf_s( L"The time is %s\n", buf );
}

The time is Fri Apr 25 13:03:39 2003

另请参阅

工时管理
asctime_s、_wasctime_s
ctime、_ctime32、_ctime64、_wctime、_wctime32、_wctime64
_ftime、_ftime32、_ftime64
gmtime_s、_gmtime32_s、_gmtime64_s
localtime_s、_localtime32_s、_localtime64_s
time、_time32、_time64