localtime, _localtime32, _localtime64

Article
06/09/2015

Convertit une valeur d'heure et corrige pour le fuseau horaire. Des versions plus sécurisées de ces fonctions sont disponibles ; consultez 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 
);

Paramètres

timer
Pointeur vers le l'horaire stockée.

Valeur de retour

Retourne un pointeur vers le résultat de structure, ou NULL si la date transmise à la fonction est :

Avant minuit, le 1er janvier 1970.
Après 3h14 : 07, le 19 janvier 2038, UTC (à _time32 et time32_t).
Après 23h59 : 59, le 31 décembre, 3000, les valeurs UTC (à _time64 et __time64_t).

_localtime64, qui utilise la structure __time64_t, permet aux dates d'être exprimées jusqu'à 23:59:59, le 31 décembre, 3000, temps universel coordonné (UTC), alors que _localtime32 représente des dates jusqu'à 03:14:07, le 19 janvier, 2038, UTC.

localtime est une fonction inline qui prend _localtime64, et time_t équivaut à __time64_t. Si vous devez forcer le compilateur à interpréter time_tcomme l'ancienne version 32 bits time_t, vous pouvez définir _USE_32BIT_TIME_T. Cela fait que localtime évalue en _localtime32. Cela n'est pas recommandé car votre application peut échouer après le 19 janvier 2038, et elle n'est pas autorisée sur les plateformes 64 bits.

Les champs de type de structure le TM stockent les valeurs suivantes, chacune desquelles est un int.

tm_sec
Les secondes après les minutes (0 à 59).
tm_min
Les minutes après les heure (0 à 59).
tm_hour
Heures après minuit (0 – 23).
tm_mday
Le jour du mois (1 à 31).
tm_mon
Le mois (0 à 11 ; Janvier = 0).
tm_year
L'année (année en cours moins 1900).
tm_wday
Le jour de la semaine (0 à 6 ; Dimanche = 0).
tm_yday
Le jour de l'année (0 à 365 ; 1er janvier = 0).
tm_isdst
Valeur positive si l'heure d'été est appliquée ; 0 si l'heure d'été n'est pas appliquée ; valeur négative si l'état d'heure d'été est inconnu. Si la variable d'environnement TZ est définie, la bibliothèque Runtime C suppose les règles appropriées aux états-unis pour implémenter le calcul de l'heure d'été (DST).

Notes

La fonction localtime convertit une heure enregistrée comme valeur time_t et stocke le résultat dans une structure de type tm. La valeur long timer représente des secondes écoulées depuis minuit (00:00:00), le 1er janvier 1970, UTC. Cette valeur est généralement obtenue à l'aide de la fonction time.

Les versions 32 bits et 64 bits de gmtime, mktime, mkgmtime, et localtime utilisent toutes une structure tm commune par thread pour la conversion. Chaque appel à une de ces routines détruit le résultat de l'appel précédent.

localtime corrige pour le fuseau horaire si l'utilisateur définit en premier la variable d'environnement global TZ. Lorsque TZ est défini, trois autres variables d'environnement (_timezone, _daylight, et _tzname) sont également définies automatiquement. Si la variable TZ n'est pas activée, localtime tente d'utiliser les informations de fuseau horaire spécifiée dans l'application de date et d'heure dans le panneau de configuration. Si ces informations ne peuvent pas être obtenues, PST8PDT, ce qui signifie que le fuseau horaire Pacifique est utilisé par défaut. Voir _tzset pour obtenir une description de ces variables. TZ est une extension Microsoft et non pas une partie de la définition ANSI standard de localtime.

Notes

L'environnement cible doit tenter de déterminer si l'enregistrement de l'heure du jour est activé.

Ces fonctions valident leurs paramètres. Si timer est un pointeur null, ou que la valeur de l'horloge est négative, ces fonctions appellent un gestionnaire de paramètre non valide, comme cela est décrit dans Validation de paramètre. Si l'exécution est autorisée à se poursuivre, les fonctions retournent NULL et attribuent à errno la valeur EINVAL.

Configuration requise

Routine	En-tête requis
localtime	<time.h>
_localtime32	<time.h>
_localtime64	<time.h>

Pour plus d'informations sur la compatibilité, consultez Compatibilité dans l'introduction.

Exemple

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