localtime_s, _localtime32_s, _localtime64_s

Articolo
06/09/2015

Converte un valore e lo corregge per il fuso orario locale. Queste sono versioni di localtime, _localtime32, _localtime64 con miglioramenti di sicurezza, come descritto in Funzionalità di sicurezza in 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 
);

Parametri

_tm
Puntatore a una struttura di tempo da compilare.
time
Puntatore al valore temporale archiviato.

Valore restituito

Zero se ha esito positivo. Il valore restituito è un codice di errore in presenza di un fallimento. I codici di errore sono definiti in Errno.h. Per un elenco di questi errori, vedere errno.

Condizioni di errore

_tm	time	Valore restituito	Valore in _tm	Richiama il gestore di parametro non valido
NULL	any	EINVAL	Non modificato	Yes
Non NULL (punta alla memoria valida)	NULL	EINVAL	Tutti i campi impostati a -1	Yes
Non NULL (punta alla memoria valida)	Minore di 0 o maggiore di _MAX__TIME64_T	EINVAL	Tutti i campi impostati a -1	No

Nel caso delle prime due condizioni di errore, viene richiamato il gestore di parametro non valido, come descritto in Convalida dei parametri. Se l'esecuzione può continuare, queste funzioni impostano errno a EINVAL e restituiscono EINVAL.

Note

La funzione _localtime32_s 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.

_localtime32_s 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, localtime32_s 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.

_localtime64_s, 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_s permette di rappresentare date fino alle 03:14:07 del 19 gennaio 2038, UTC.

localtime_s è una funzione inline che valuta _localtime64_s, e time_t equivale a __time64_t. Se è necessario forzare il compilatore ad interpretare time_t come l'obsoleto time_t a 32 bit, è possibile definire _USE_32BIT_TIME_T. In questo modo localtime_s valuterà _localtime32_s. 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 il 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).

Requisiti

Routine	Intestazione obbligatoria
localtime_s	<time.h>
_localtime32_s	<time.h>
_localtime64_s	<time.h>

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

Esempio

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