asctime, asctime_s

 

C

編譯器支援

語言

標頭檔案

型別支援

程式工具

變參函式支援

錯誤處理

動態記憶體管理

字串庫

演算法

數值

日期和時間工具

輸入/輸出支援

本地化支援

併發支援 (C11)

技術規範

符號索引

 

日期和時間工具

函式

時間操作

difftime

time

clock

timespec_get (C11)

timespec_getres (C23)

格式轉換

asctimeasctime_s (C23 中已廢棄)(C11)

ctimectime_s (C23 中已廢棄)(C11)

strftime

wcsftime (C95)

gmtimegmtime_rgmtime_s (C23)(C11)

localtimelocaltime_rlocaltime_s (C23)(C11)

mktime

常量

CLOCKS_PER_SEC

型別

tm

time_t

clock_t

timespec (C11)

 

定義於標頭檔案 <time.h>
	(1)
char*                asctime( const struct tm* time_ptr );			(直至 C23)
[[deprecated]] char* asctime( const struct tm* time_ptr );			(自 C23 起)
errno_t asctime_s( char* buf, rsize_t bufsz, const struct tm* time_ptr );		(2)	(C11 起)

1) 將給定日曆時間 tm 轉換為以下固定 25 字元格式的文字表示形式： Www Mmm dd hh:mm:ss yyyy\n

• Www - 來自 time_ptr->tm_wday 的三字母英文縮寫星期幾，之一為 Mon, Tue, Wed, Thu, Fri, Sat, Sun。
• Mmm - 來自 time_ptr->tm_mon 的三字母英文縮寫月份名，之一為 Jan, Feb, Mar, Apr, May, Jun, Jul, Aug, Sep, Oct, Nov, Dec。
• dd - 來自 timeptr->tm_mday 的兩位日期，如同用 sprintf 和 %2d 列印。
• hh - 來自 timeptr->tm_hour 的兩位小時，如同用 sprintf 和 %.2d 列印。
• mm - 來自 timeptr->tm_min 的兩位分鐘，如同用 sprintf 和 %.2d 列印。
• ss - 來自 timeptr->tm_sec 的兩位秒鐘，如同用 sprintf 和 %.2d 列印。
• yyyy - 來自 timeptr->tm_year + 1900 的四位年份，如同用 sprintf 和 %4d 列印。

如果 *time_ptr 的任何成員超出其正常範圍，則行為未定義。

如果 time_ptr->tm_year 指示的日曆年超過 4 位或小於 1000 年，則行為未定義。

該函式不支援本地化，且換行符無法移除。

該函式修改靜態儲存，且非執行緒安全。

此函式已廢棄，不應在新程式碼中使用。

(自 C23 起)

2) 同 (1)，除了訊息寫入使用者提供的儲存 buf（保證以空字元結尾），且以下錯誤在執行時檢測到並呼叫當前安裝的約束處理函式

• buf 或 time_ptr 為空指標
• bufsz 小於 26 或大於 RSIZE_MAX
• *time_ptr 的所有成員都不在其正常範圍內
• time_ptr->tm_year 指示的年份小於 0 或大於 9999。

如同所有邊界檢查函式，僅當實現定義了 __STDC_LIB_EXT1__ 且使用者在包含 <time.h> 之前將 __STDC_WANT_LIB_EXT1__ 定義為整數常量 1 時，才保證 asctime_s 可用。

引數

time_ptr	-	指向指定要列印時間的 tm 物件的指標
buf	-	指向使用者提供的至少 26 位元組長度緩衝區的指標
bufsz	-	使用者提供的緩衝區的大小

返回值

1) 指向靜態空終止字元字串的指標，該字串包含如上所述的日期和時間的文字表示。該字串可能在 asctime 和 ctime 之間共享，並且可能在每次呼叫這些函式中的任何一個時被覆蓋。

2) 成功時返回零，失敗時返回非零，在這種情況下 buf[0] 設定為零（除非 buf 為空指標或 bufsz 為零或大於 RSIZE_MAX）。

注意

asctime 返回指向靜態資料的指標，且非執行緒安全。POSIX 將此函式標記為已過時，並建議改用 strftime。C 標準也建議改用 strftime 而非 asctime 和 asctime_s，因為 strftime 更靈活且對本地化敏感。

POSIX 僅在輸出字串長度超過 25 個字元，或 timeptr->tm_wday 或 timeptr->tm_mon 不在預期範圍內，或 timeptr->tm_year 超過 INT_MAX - 1990 時，才限制未定義行為。

一些實現將 timeptr->tm_mday == 0 處理為表示前一個月的最後一天。

示例

執行此程式碼

#define __STDC_WANT_LIB_EXT1__ 1
#include <stdio.h>
#include <time.h>
 
int main(void)
{
    struct tm tm = *localtime(&(time_t){time(NULL)});
    printf("%s", asctime(&tm)); // note implicit trailing '\n'
 
#ifdef __STDC_LIB_EXT1__
    char str[26];
    asctime_s(str, sizeof str, &tm);
    printf("%s", str);
#endif
}

可能的輸出

Tue May 26 21:51:50 2015
Tue May 26 21:51:50 2015

參考

• C17 標準 (ISO/IEC 9899:2018)

• 7.27.2.1 asctime 函式 (p: 287)

• K.3.8.2.1 asctime_s 函式 (p: 453-454)

• C11 標準 (ISO/IEC 9899:2011)

• 7.27.2.1 asctime 函式 (p: 392-393)

• K.3.8.2.1 asctime_s 函式 (p: 624-625)

• C99 標準 (ISO/IEC 9899:1999)

• 7.23.3.1 asctime 函式 (p: 341-342)

• C89/C90 標準 (ISO/IEC 9899:1990)

• 4.12.3.1 asctime 函式

亦參見

ctimectime_s (C23 中已廢棄)(C11)	將 time_t 物件轉換為文字表示形式 (函式)
strftime	將 tm 物件轉換為自定義文字表示形式 (函式)
C++ 文件 對應 asctime