localtime_s、_localtime32_s、_localtime64_s

發行項
06/09/2015

轉換時間值並為本地時區修正。這些是 localtime, _localtime32, _localtime64 的安全性增強版本，如 CRT 中的安全性功能.中所述。

errno_t localtime_s(
   struct tm* _tm,
   const time_t *time 
);
errno_t _localtime32_s(
   struct tm* _tm,
   const time32_t *time 
);
errno_t _localtime64_s(
   struct tm* _tm,
   const _time64_t *time 
);

參數

_tm
out 要填入的時間結構的指標。
time
儲存時間的指標。

傳回值

如果成功，則為零。如果發生失敗，則傳回值為錯誤碼。錯誤碼在 Errno.h 中定義。如需這些錯誤的清單，請參閱 errno。

錯誤狀況

_tm	time	傳回值	在 _tm 的值	叫用無效的參數處理常式。
NULL	any	EINVAL	未修改	有
不是 NULL (指向有效的記憶體)	NULL	EINVAL	所有欄位設定為 -1	有
不是 NULL (指向有效的記憶體)	小於 0 或大於_MAX__TIME64_T	EINVAL	所有欄位設定為 -1	沒有

在前兩個錯誤條件下，無效的參數叫用處理常式，如參數驗證中所述。如果允許繼續執行，這些函式會將 errno 設定為 EINVAL 並傳回 EINVAL。

備註

_localtime32_s 函式在型別 tm結構轉換為 time_t 值儲存的時間並儲存結果。 long 值的 timer 表示秒數 (從 00:00: 00 經過)， 1970 年 1 月 1 日 UTC。這個值會從 time 函式通常取得。

如果使用者第一次設定全域環境變數 TZ，_localtime32_s 為本地時區修正。當 TZ 設定為時，其他三個環境變數 (_timezone、 _daylight和 _tzname) 自動設定。如果 TZ 變數不會設定， localtime32_s 在控制台嘗試使用在日期/時間應用程式指定的時區資訊。如果無法取得這項資訊，預設會使用表示太平洋時區的 PST8PDT。為這些變數的說明請參閱 _tzset 。 TZ 是 localtime的 ANSI 標準定義的而不是 Microsoft 擴充部分。

注意事項
目標環境應該嘗試判斷日光節約時間是否為作用中。

_localtime64_s，使用 __time64_t 結構，允許日期透過 23:59 來表示: 59， 3000 年 12 月 31 日， Coordinated Universal Time (UTC)，，，而 _localtime32_s 傳遞代表日期 UTC 2038年 1 月 19 日，03:14: 07。

localtime_s 是 _localtime64_s和 time_t的評估與 __time64_t相等的內嵌函式。如果您需要強制編譯器解譯 time_t做為舊 32 位元 time_t，您可以定義 _USE_32BIT_TIME_T。這麼做會使 localtime_s評估為 _localtime32_s。並不建議這麼做，因為您的應用程式可能在 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; 1 一月 = 0)。
tm_year
年 (今年年數減去 1900)。
tm_wday
星期幾 (0 – 6; 星期日 = 0)。
tm_yday
日期 (0 – 365; 1 月 1 日 = 0 )。
tm_isdst
如果日光節約時間生效為正數值；如果日光節約時間未生效則為0；如果日光節約時間狀態不明則為負數值。如果 TZ 設定環境變數， C 執行階段程式庫假設規則適用於實作的日光節約時間 (DST) 的計算美國。

需求

常式	必要的標頭
localtime_s	<time.h>
_localtime32_s	<time.h>
_localtime64_s	<time.h>

如需更多關於相容性的資訊，請參閱入門介紹中的相容性 (Compatibility) 。

範例

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