localtime, _localtime32, _localtime64

Articolo
06/09/2015

Convertire un valore e lo correggerlo per il fuso orario locale. Sono disponibili versioni più sicure di queste funzioni. Vedere 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 
);

Parametri

timer
Puntatore all'ora archiviata.

Valore restituito

Restituire un puntatore al risultato della struttura, o a NULL se la data passata alla funzione è:

Prima di mezzanotte, il 1° gennaio 1970.
Dopo le 03:14:07 del 19 gennaio 2038, UTC (utilizzando _time32 e di time32_t).
Dopo le 23:59:59 del 31 dicembre 3000, UTC (utilizzando _time64 e di __time64_t).

_localtime64, che utilizza la struttura __time64_t, permette di esprimere date fino alle 23:59: 59 del il 31 dicembre 3000, UTC (coordinated universal time), mentre _localtime32 permette di rappresentare date fino alle 03:14:07 del 19 gennaio 2038, UTC.

localtime è una funzione inline che valuta _localtime64, e time_t equivale a __time64_t. Se è necessario forzare il compilatore ad interpretare time_tcome il vecchio 32 bit time_t, è possibile definire _USE_32BIT_TIME_T. In questo modo localtime valuterà _localtime32. Questa operazione non è consigliabile perché l'applicazione fallirebbe dopo il 19 gennaio 2038, e ciò non è consentito su piattaforme a 64 bit.

I campi della struttura di tipo tm memorizzano i seguenti valori, ognuno dei quali è un int:

tm_sec
Secondi dopo un minuto (0 – 59).
tm_min
Minuti dopo un'ora (0 – 59).
tm_hour
Ore dopo la mezzanotte (da 0 a 23).
tm_mday
Giorno del mese (1 – 31).
tm_mon
Mese (0 – 11; Gennaio = 0).
tm_year
Anno (anno corrente meno 1900).
tm_wday
Giorno della settimana (0 – 6; Domenica = 0).
tm_yday
Giorno dell'anno (0 – 365; Gennaio 1 = 0).
tm_isdst
Un valore positivo se è in vigore l'ora legale; 0 se non è in vigore l'ora legale; un valore negativo se lo stato dell'ora legale è sconosciuto. Se la variabile di ambiente TZ è impostata, la libreria di run-time del linguaggio C presuppone le regole appropriate per Stati Uniti per implementare il calcolo dell'ora legale (DST).

Note

La funzione localtime converte un'ora memorizzata come un valore time_t e salva il risultato in una struttura dati di tipo tm. Il valore long timer rappresenta i secondi trascorsi dalla mezzanotte (00:00:00) del 1° gennaio 1970, UTC. Questo valore è in genere ottenuto dalla funzione time.

Sia le versioni a 32 bit che a 64 bit di gmtime, mktime, mkgmtime e localtime utilizzano una singola struttura tm per ogni thread utilizzata per la conversione. Ogni chiamata a una di queste routine distrugge il risultato della chiamata precedente.

localtime corregge il fuso orario locale se prima l'utente imposta la variabile di ambiente globale TZ. Quando TZ è impostato, vengono impostate automaticamente anche altre tre variabili di ambiente (_timezone, _daylight e _tzname). Se la variabile TZ non è impostata, localtime tenta di utilizzare le informazioni del fuso orario specificate nell'applicazione data/ora nel Pannello di controllo. Se tale informazione non può essere ottenuta, viene utilizzato PST8PDT per impostazione predefinita, ovvero il fuso orario del Pacifico. Vedere _tzset per una descrizione di tali variabili. TZ è un'estensione Microsoft e non una parte della definizione standard ANSI di localtime.

Nota

L'ambiente di destinazione deve tentare di determinare se è in vigore l'ora legale.

Queste funzioni convalidano i parametri. Se timer è un puntatore null, oppure se il valore temporale è negativo, queste funzioni richiamano un gestore di parametro non valido, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, la funzione restituisce NULL e imposta errno su EINVAL.

Requisiti

Routine	Intestazione obbligatoria
localtime	<time.h>
_localtime32	<time.h>
_localtime64	<time.h>

Per ulteriori informazioni sulla compatibilità, vedere Compatibilità nell'Introduzione.

Esempio

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