localtime、_localtime32、_localtime64

發行項
06/09/2015

轉換時間值並為本地時區修正。這些函式已有更安全的版本可用，請參閱 localtime_s、_localtime32_s、_localtime64_s。

struct tm *localtime(
   const time_t *timer 
);
struct tm *_localtime32(
   const __time32_t *timer
);
struct tm *_localtime64(
   const __time64_t *timer 
);

參數

timer
要儲存時間的指標。

傳回值

請回傳結構結果指標或 NULL，當傳遞至函式的日期為 :

在1970 年 1 月 1 日午夜之前。
在 2038 年 1 月 19 日03:14:07 UTC之後，(使用_time32 和 time32_t)。
在 3000 年 12 月 31 日23:59:59，UTC之後，(使用 _time64 和 __time64_t)。

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

localtime 是 _localtime64和 time_t的評估與 __time64_t相等的內嵌函式。如果您需要強制編譯器解譯 time_t做為舊 32 位元， time_t您可以定義_USE_32BIT_TIME_T。這麼做會使 localtime評估為 _localtime32。並不建議這麼做，因為您的應用程式可能在 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 函式在型別 tm結構轉換為 time_t 值儲存的時間並儲存結果。 long 值的 timer 表示秒數 (從 00:00: 00 經過)， 1970 年 1 月 1 日 UTC。這個值會從 time 函式通常取得。

32 位元和 64 位元版本的 gmtime、 mktime、 mkgmtime和 localtime 使用每個轉換執行緒都使用單一的 tm 結構。每個呼叫這些常式都會終結之前呼叫的結果。

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

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

這些函式會驗證它們的參數。如果 timer 是無效的檔案指標或者此計時器的值為負數時，這些函數會產生一個非正確指標處理式，如參數驗證所述。如果允許繼續執行，函式會傳回 NULL 並將 errno 設定為 EINVAL。

需求

常式	必要的標頭
localtime	<time.h>
_localtime32	<time.h>
_localtime64	<time.h>

如需其他相容性資訊，請參閱＜簡介＞中的相容性。

範例

// crt_localtime.cpp
// compile with: /W3
/* This program uses _time64 to get the current time 
 * and then uses localtime64() 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;

        _time64( &long_time );           // Get time as 64-bit integer.
                                         // Convert to local time.
        newtime = _localtime64( &long_time ); // C4996
        // Note: _localtime64 deprecated; consider _localetime64_s

        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;

        char buff[30];
        asctime_s( buff, sizeof(buff), newtime );
        printf( "%.19s %s\n", buff, am_pm );
}