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
通常是從 或 的呼叫 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;January = 0) |
tm_sec |
分鐘後秒 (0-59) |
tm_wday |
一周中的一天 (0-6;星期日 = 0) |
tm_yday |
一年中的一天 (0-365;1 月 1 = 0) |
tm_year |
年份 (目前年份減去 1900 年) |
已轉換的字元字串也會根據當地時區設定調整。 如需設定當地時間的相關資訊,請參閱 、、、 _time64
_ftime64
_ftime32
_ftime
和 、、 _localtime32_s
_localtime64_s
函 localtime_s
式。 _time32
time
如需定義時區環境和全域變數的相關資訊,請參閱 _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
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應