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 物件的指標。

傳回值

如果成功，則為零。 如果失敗，則會叫用無效的參數處理程式，如參數驗證中所述。 如果允許繼續執行，傳回值為錯誤碼。 錯誤碼於 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通常是從 或的呼叫gmtimelocaltime取得。 這兩個函式都可用來填入 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;January = 0）
tm_sec	分鐘後秒 （0-59）
tm_wday	一周中的一天 （0-6;星期日 = 0）
tm_yday	一年中的一天 （0-365;1 月 1 = 0）
tm_year	年份 (目前年份減去 1900 年)

已轉換的字元字串也會根據當地時區設定調整。 如需設定當地時間的相關信息，請參閱 、、、_time64_ftime64_ftime_ftime32 和 、、 _localtime32_s_localtime64_s函localtime_s式。 _time32time 如需定義時區環境和全域變數的相關信息，請參閱 _tzset。

asctime_s 所產生的字串結果剛好包含 26 個字元，且具有以下格式 Wed Jan 2 02:03:55 1980\n\0。 使用 24 小時制。 所有欄位都具有固定寬度。 新行字元和 Null 字元佔用字串的最後兩個位置。 傳入的值 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