共用方式為

localtime、 、 _localtime32_localtime64

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

語法

struct tm *localtime( const time_t *sourceTime ); // See note in remarks section about linkage
struct tm *_localtime32( const __time32_t *sourceTime );
struct tm *_localtime64( const __time64_t *sourceTime );

參數

sourceTime
預存時間的指標。

傳回值

將指標傳回結構結果，或 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，允許表示至國際標準時間 (UTC) 3000 年 12 月 31 日 23:59:59 為止的日期，而 _localtime32 則表示至 2038 年 1 月 18 日23:59:59 UTC為止的日期。

localtime 是評估為 _localtime64 的內嵌函式，而 time_t 相當於 __time64_t。 如果您要強制編譯器將 time_t 解譯為舊的 32 位元 time_t，您可以定義 _USE_32BIT_TIME_T。 _USE_32BIT_TIME_T 會導致 localtime 評估為 _localtime32。 不建議使用 _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；1 月 = 0)。
tm_year 年份 (目前年份減去 1900)。
tm_wday 週中的日 (0 - 6；星期日 = 0)。
tm_yday 一年中的日 (0─365；1 月 1 日 = 0)。
tm_isdst 如果日光節約時間生效，則為正值;如果日光節約時間無效，則為0;如果日光節約時間的狀態未知，則為負值。

如果已設定 TZ 環境變數，C 執行階段程式庫將假設適用於美國之規則，以實作日光節約時間 (DST) 的計算。

備註

函 localtime 式會轉換儲存為 time_t 值的時間，並將結果儲存在 型 tm別的結構中。 long 值 sourceTime 代表從 1970 年 1 月 1 日 UTC 午夜 (00: 00:00) 以來經過的秒數。 此值通常會從函 time 式取得。

32 位元和 64 位元版本的 gmtime、mktime、mkgmtime，和 localtime 進行轉換時每個執行緒都使用單一的 tm 結構。 每呼叫其中一個此類常式會導致先前呼叫結果的終結。

如果使用者第一次設定全域環境變數 localtime，TZ 會為本地時區進行校正。 當已設定 TZ 時，其他三個環境變數 (_timezone、_daylight和 _tzname) 也會自動設定。 TZ如果未設定變數，localtime請嘗試使用 控制台 中 Date/Time 應用程式中指定的時區資訊。 如果無法取得這項資訊，預設會使用表示太平洋時區的PST8PDT。 如需這些變數的描述，請參閱 _tzset 。 TZ 是 Microsoft 延伸模組，且並不屬於 ANSI 標準定義的 localtime。

注意

目標環境應該嘗試判斷日光節約時間是否生效。

這些函式會驗證它們的參數。 如果 sourceTime 是 Null 指標，或者sourceTime如果值為負數，則這些函式會叫用無效的參數處理程式，如參數驗證中所述。 如果允許繼續執行，這些函式會傳回 NULL，並將 errno 設定為 EINVAL。

根據預設，此函式的全域狀態會限定於應用程式。 若要變更此行為，請參閱 CRT 中的全域狀態。

注意

當您同時使用 Windows SDK 10.0.26100.6901 版和 Visual Studio 2026 或更新版本時， localtime 不再 static inline 是 （內部連結）。 相反，它是 inline （外部連結）。
若要在包含任何 CRT 標頭之前， #define _STATIC_INLINE_UCRT_FUNCTIONS=1 先回到先前的行為。 預設會將 _STATIC_INLINE_UCRT_FUNCTIONS 設定為 0。
這項變更可增加 UCRT 與 C++ 標準的一致性，並改善與 C++ 模組的相容性。

需求

常式 必要的 C 標頭 必要的 C++ 標頭
localtime、 、 _localtime32_localtime64 <time.h> <ctime> 或 <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 );
}

Tue Feb 12 10:05:58 AM

另請參閱

時間管理
asctime、_wasctime
ctime、、_ctime32_ctime64、_wctime、、_wctime32、_wctime64
_ftime、 、 _ftime32_ftime64
gmtime、 、 _gmtime32_gmtime64
localtime_s、 、 _localtime32_s_localtime64_s
time、 、 _time32_time64
_tzset

  • Last updated on