asctime_s、_wasctime_s

發行項
06/09/2015

轉換 tm 時間結構成字元字串。這些是 asctime、_wasctime 的安全性增強版本，如 CRT 中的安全性功能中所述。

errno_t asctime_s( 
   char* buffer,
   size_t numberOfElements,
   const struct tm *_tm 
);
errno_t _wasctime_s( 
   wchar_t* buffer,
   size_t numberOfElements
   const struct tm *_tm 
);
template <size_t size>
errno_t asctime_s( 
   char (&buffer)[size],
   const struct tm *_tm 
); // C++ only
template <size_t size>
errno_t _wasctime_s( 
   wchar_t (&buffer)[size],
   const struct tm *_tm 
); // C++ only

參數

buffer
[out] 儲存結果字串之緩衝區的指標。這個函式採用指標到具有 numberOfElements指定大小的有效的記憶體位置。
numberOfElements
[in] 用來儲存結果的緩衝區大小。
_tm
[in] Time/date 結構這個函式採用指標到有效的 struct tm 物件。

傳回值

如果成功，則為零。如果有失敗，就會叫用無效參數處理常式，如參數驗證中所述。如果執行允許繼續執行，則傳回值為錯誤碼。錯誤碼在 ERRNO.H 中定義。如需詳細資訊，請參閱errno 常數。為每個錯誤條件傳回的實際錯誤碼如下表中所示。

錯誤狀況

buffer	numberOfElements	tm	傳回	在 buffer 的值
NULL	Any	Any	EINVAL	未修改
不是 NULL (指向有效的記憶體)	0	Any	EINVAL	未修改
非NULL	0< size < 26	Any	EINVAL	空字串
非NULL	>= 26	NULL	EINVAL	空字串
非NULL	>= 26	無效的時間結構或超出時間元件的範圍值	EINVAL	空字串

注意事項
wasctime_s 的錯誤狀況類似於 asctime_s ，除了大小限制在文字測量。

備註

asctime 函式會轉換為結構儲存的時間為字元字串。 _tm 值通常取得來自對 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 月 1 日 = 0 )
tm_year	年 (今年年數減去 1900)

要轉換的字元字串也會根據當地時區設定調整。請參閱 time、_time32、_time64, _ftime、_ftime32、_ftime64，如需配置本地時間的詳細資訊請參閱 localtime_s、_localtime32_s、_localtime64_s 函式，而定義時區環境和全域變數的詳細資訊請參閱 _tzset 函式。

asctime_s 所產生的結果字串會包含 26 個字元且格式為 Wed Jan 02 02:03:55 1980\n\0。使用 24 小時制。所有欄位具有相同的寬度。新行字元和 null 字元佔用字串的前兩個位置。做為第二個參數傳遞的值至少在這必須這麼大。如果較少，將會傳回錯誤碼 EINVAL。

_wasctime_s 是 asctime_s的寬字元版本。 _wasctime_s 和 asctime_s 其餘行為相同。

一般文字常式對應

TCHAR.H 常式	_UNICODE & _MBCS 未定義	_MBCS 已定義	_UNICODE 已定義
_tasctime_s	asctime_s	asctime_s	_wasctime_s

在 C++ 中，這些函式的使用被簡化為使用樣板多載；使用多載可以自動推斷緩衝區的大小而不必在參數中指明大小。如需詳細資訊，請參閱安全範本多載。

需求

常式	必要的標頭
asctime_s	<time.h>
_wasctime_s	<time.h> or <wchar.h>

安全性

如果緩衝區指標不是 NULL ，而且指標未指向有效的緩衝區，函式會覆寫所在位置。這也可能造成存取違規。

如果傳入的引數大小大於緩衝區的實際大小，緩衝區滿溢會發生。

範例

這個程式以長整數 aclock 存放系統時間，使用 asctime_s 函式，將它轉譯成結構 newtime 然後轉換成輸出的字串形式。

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