time.h

<time.h> et <ctime> sont des en-têtes, respectivement de la bibliothèque standard du langage C et du C++, qui déclarent des fonctions fournissant de manière standardisée des primitives de manipulation des dates et leur formatage.

Fonctions

char *asctime(const struct tm* tmptr)

Convertit tmptr en une chaîne de caractères au format Www Mmm dd hh:mm:ss yyyy, où Www est le jour de la semaine, Mmm est le mois en lettres, dd le jour du mois, hh:mm:ss est l'heure, et yyyy est l'année. La chaîne est suivie d'un retour à la ligne et d'un caractère de fin de chaîne, pour un total de 26 caractères. La chaîne donnée en résultat est allouée statiquement et partagée par les fonctions ctime et asctime. À chaque fois qu'une des deux fonctions est appelée, le contenu cette chaîne est remplacé.

clock_t clock(void)

Retourne une approximation du temps processeur utilisé par le processus.

char* ctime(const time_t* timer)

Convertit la valeur timer en une chaîne au même format que asctime. La chaîne retournée est allouée statiquement dans une zone partagée avec asctime. ctime utilise le buffer interne de gmtime et localtime en pointeur de retour, un appel à cette fonction en entrainera donc l'écrasement.

double difftime(time_t timer2, time_t timer1)

Retourne la différence, exprimée en secondes entre deux instants.

struct tm* gmtime(const time_t* timer)

Convertit une valeur de type time_t en une structure tm en temps UTC. Cette structure est allouée statiquement et partagée par les fonctions gmtime, localtime et ctime. À chaque fois qu'une de ces fonctions est appelée, le contenu de la structure est écrasé.

struct tm* gmtime_r(const time_t* timer, struct tm* result)

Convertit une valeur de type time_t en une structure tm en temps UTC. La date est stockée dans la structure tm pointée par result. Ceci est une version compatible avec les threads de gmtime.

struct tm* localtime(const time_t* timer)

Convertit une valeur de type time_t en une structure tm à l'heure locale. Cette structure est allouée statiquement et partagée par les fonctions gmtime, localtime et ctime. À chaque fois qu'une de ces fonctions est appelée, le contenu de la structure est écrasé.

time_t mktime(struct tm* ptm)

Convertit une structure tm en une valeur de type time_t. mktime vérifie la structure tm, en corrigeant les valeurs de ses attributs si elles sont mal renseignées, et traduit cette structure en une valeur time_t qui est retournée. Les valeurs d'origine des champs tm_wday et tm_yday (jour de la semaine et de l'année) de ptm sont ignorées, mais les champs sont remplis avec les valeurs qui correspondent à la date calculée. La valeur de tm_day n'est pas vérifiée jusqu'à ce que tm_wday et tm_yday soient déterminés. En cas d'erreur, la fonction retourne la valeur (time_t)-1.

time_t time(time_t* timer)

Donne le temps actuel. La valeur est stockée dans l'objet pointé par timer. Dans le cas où timer est nul, la valeur est seulement passée en résultat de la fonction. La norme C spécifie que le type time_t est arithmétique, mais que son encodage n'est pas spécifié, ce qui rend ce type pratiquement opaque. Le standard POSIX spécifie que time_t contient le nombre de secondes depuis le 1^er janvier 1970 (heure UNIX).

size_t strftime(char* s, size_t n, const char* format, const struct tm* tptr)

Formate la structure tm en une chaîne de caractères, écrite dans s, qui contient au plus n caractères.

Constantes

CLK_PER_SEC

Constante qui définit le nombre de coups d'horloge par seconde. Elle est utilisée par la fonction clock().

CLOCKS_PER_SEC

Une autre nom de CLK_PER_SEC utilisé par quelques bibliothèques.

CLK_TCK

Une macro obsolète de CLK_PER_SEC.

Types de données

clock_t

Type de données retourné par clock().
Généralement défini par les types int ou long int.

time_t

Type de données retourné par time().
Généralement défini par les types int ou long int.

struct tm

Représentation humaine et calendaire des dates.

Temps calendaire

La représentation humaine des dates ("broken-down time" en anglais) est représentée dans la bibliothèque standard C par la structure struct tm dont voici les membres:

Membre	Description
int tm_hour	heure (0 - 23)
int tm_isdst	Indicateur sur le décalage entre heure d'hiver et heure d'été: vaut 1 si le décalage est actif, 0 s'il ne l'est pas et une valeur négative si l'information n'est pas disponible.
int tm_mday	jour du mois (1 - 31)
int tm_min	minutes (0 - 59)
int tm_mon	mois (0 - 11, 0 correspond à janvier)
int tm_sec	secondes (0 - 59)
int tm_wday	jour de la semaine (0-6, 0 correspond à dimanche)
int tm_yday	jour de l'année (0 - 365)
int tm_year	nombre d'années écoulées depuis 1900

Références

• (en) The GNU C Library ReferenceManual, 6 juillet 2001 (lire en ligne), « Calendar Time »
• (en) The Open Group BaseSpecifications, 9 décembre 2008 (lire en ligne), « gmtime »