localtime_s
, _localtime32_s
, _localtime64_s
將 time_t
時間值轉換為 tm
結構,並更正當地時區。 這些函式是 的版本 localtime
, _localtime32
_localtime64
具有 CRT 中安全性功能中所述 的安全性增強功能。
語法
errno_t localtime_s(
struct tm* const tmDest,
time_t const* const sourceTime
);
errno_t _localtime32_s(
struct tm* tmDest,
__time32_t const* sourceTime
);
errno_t _localtime64_s(
struct tm* tmDest,
__time64_t const* sourceTime
);
參數
tmDest
要填入之時間結構的指標。
sourceTime
預存時間的指標。
傳回值
如果成功,則為零。 如果失敗,傳回值就是錯誤碼。 錯誤碼定義于 中 Errno.h
。 如需這些錯誤的清單,請參閱 errno
。
錯誤條件
tmDest |
sourceTime |
傳回值 | tmDest 中的值 |
叫用無效的參數處理常式 |
---|---|---|---|---|
NULL |
任意 | EINVAL |
未修改 | Yes |
非 NULL (指向有效的記憶體) |
NULL |
EINVAL |
所有的欄位設定為 -1 | Yes |
非 NULL (指向有效的記憶體) |
小於 0 或大於 _MAX__TIME64_T |
EINVAL |
所有的欄位設定為 -1 | No |
前兩個錯誤條件會叫用不正確參數處理常式,如參數驗證 中所述 。 如果允許繼續執行,這些函式會將 errno
設為 EINVAL
,並傳回 EINVAL
。
備註
函 localtime_s
式會轉換儲存為 time_t
值的時間,並將結果儲存在 型 tm
別 的結構中。 time_t
值 sourceTime
代表從 1970 年 1 月 1 日 UTC 午夜 (00: 00:00) 以來經過的秒數。 此值通常會從 函 time
式取得。
如果使用者第一次設定全域環境變數 TZ
,localtime_s
會為本地時區進行校正。 當已設定 TZ
時,其他三個環境變數 (_timezone
、_daylight
和 _tzname
) 也會自動設定。 TZ
如果未設定變數, localtime_s
請嘗試使用 主控台 中日期/時間應用程式中指定的時區資訊。 如果無法取得這項資訊,預設會使用表示太平洋時區的PST8PDT。 如需這些變數的描述,請參閱 _tzset
。 TZ
是 Microsoft 延伸模組,且並不屬於 ANSI 標準定義的 localtime
。
注意
目標環境應該嘗試判斷日光節約時間是否生效。
_localtime64_s
會使用__time64_t
結構,允許表示至國際標準時間 (UTC) 3001 年 1 月 18 日 23:59:59 為止的日期,而 _localtime32_s
則表示至 2038 年 1 月 18 日 23:59:59 UTC 為止的日期。
localtime_s
是評估為 _localtime64_s
的內嵌函式,而 time_t
相當於 __time64_t
。 如果您需要強制編譯器將解譯 time_t
為舊的 32 位 time_t
,您可以定義 _USE_32BIT_TIME_T
,這會導致 localtime_s
評估為 _localtime32_s
。 不建議使用 _USE_32BIT_TIME_T
,因為您的應用程式可能會在 2038 年 1 月 18 日之後失敗,而且 64 位平臺上不允許它。
結構類型的 tm
欄位會儲存下列值,每個值都是 int
。
欄位 | 描述 |
---|---|
tm_sec |
分鐘後幾秒(0 - 59)。 |
tm_min |
小時後分鐘 (0 - 59)。 |
tm_hour |
午夜(0 - 23)以來的小時。 |
tm_mday |
月日 (1 - 31)。 |
tm_mon |
月 (0 - 11;January = 0)。 |
tm_year |
年份 (目前年份減去 1900)。 |
tm_wday |
一周中的一天 (0 - 6;星期日 = 0)。 |
tm_yday |
一年中的一天 (0 - 365;1 月 1 日 = 0)。 |
tm_isdst |
如果日光節約時間生效,則為正值;如果日光節約時間無效,則為 0;如果日光節約時間的狀態未知,則為負值。 |
如果 TZ
環境變數已設定,C 執行階段程式庫將假設適用於美國之規則,以實作日光節約時間 (DST) 的計算。
根據預設,此函式的全域狀態會限定于應用程式。 若要變更此行為,請參閱 CRT 中的全域狀態。
需求
常式 | 必要的 C 標頭 | 必要的 C++ 標頭 |
---|---|---|
localtime_s , _localtime32_s , _localtime64_s |
<time.h> |
<ctime> 或 <time.h> |
如需相容性詳細資訊,請參閱相容性。
範例
// crt_localtime_s.c
// This program uses _time64 to get the current time
// and then uses _localtime64_s() to convert this time to a structure
// representing the local time. The program converts the result
// from a 24-hour clock to a 12-hour clock and determines the
// proper extension (AM or PM).
#include <stdio.h>
#include <string.h>
#include <time.h>
int main( void )
{
struct tm newtime;
char am_pm[] = "AM";
__time64_t long_time;
char timebuf[26];
errno_t err;
// Get time as 64-bit integer.
_time64( &long_time );
// Convert to local time.
err = _localtime64_s( &newtime, &long_time );
if (err)
{
printf("Invalid argument to _localtime64_s.");
exit(1);
}
if( newtime.tm_hour > 12 ) // Set up extension.
strcpy_s( am_pm, sizeof(am_pm), "PM" );
if( newtime.tm_hour > 12 ) // Convert from 24-hour
newtime.tm_hour -= 12; // to 12-hour clock.
if( newtime.tm_hour == 0 ) // Set hour to 12 if midnight.
newtime.tm_hour = 12;
// Convert to an ASCII representation.
err = asctime_s(timebuf, 26, &newtime);
if (err)
{
printf("Invalid argument to asctime_s.");
exit(1);
}
printf( "%.19s %s\n", timebuf, am_pm );
}
Fri Apr 25 01:19:27 PM
另請參閱
時間管理
asctime_s
, _wasctime_s
ctime
, _ctime32
, _ctime64
, _wctime
, _wctime32
, _wctime64
_ftime
, _ftime32
, _ftime64
gmtime_s
, _gmtime32_s
, _gmtime64_s
localtime
, _localtime32
, _localtime64
time
, _time32
, _time64
_tzset
意見反應
https://aka.ms/ContentUserFeedback。
即將登場:在 2024 年,我們將逐步淘汰 GitHub 問題作為內容的意見反應機制,並將它取代為新的意見反應系統。 如需詳細資訊,請參閱:提交並檢視相關的意見反應