#include <time.h> char *asctime(const struct tm *tm); char *asctime_r(const struct tm *tm, char *buf); char *ctime(const time_t *timep); char *ctime_r(const time_t *timep, char *buf); struct tm *gmtime(const time_t *timep); struct tm *gmtime_r(const time_t *timep, struct tm *result); struct tm *localtime(const time_t *timep); struct tm *localtime_r(const time_t *timep, struct tm *result); time_t mktime(struct tm *tm);
Exigences de macros de test de fonctionnalités pour la glibc (voir feature_test_macros(7)) :
asctime_r(),
ctime_r(),
gmtime_r(),
localtime_r() :
_POSIX_C_SOURCE || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE
Les fonctions asctime() et mktime() utilisent toutes deux un argument de type struct tm, c'est-à-dire une représentation binaire divisée en année, mois, jour, heure...
Cette structure tm est définie dans <time.h> comme suit :
struct tm { int tm_sec; /* secondes */ int tm_min; /* minutes */ int tm_hour; /* heures */ int tm_mday; /* quantième du mois */ int tm_mon; /* mois (0 à 11 !) */ int tm_year; /* année */ int tm_wday; /* jour de la semaine */ int tm_yday; /* jour de l'année */ int tm_isdst; /* décalage horaire */ };
Les membres de la structure tm sont :
L'appel ctime(t) est équivalent à asctime(localtime(t)). Il convertit la date t en une chaîne de caractères de la forme
Les abréviations des jours de la semaine sont « Sun », « Mon », « Tue », « Wed », « Thu », « Fri », et « Sat ». Les abréviations des mois sont « Jan », « Feb », « Mar », « Apr », « May », « Jun », « Jul », « Aug », « Sep », « Oct », « Nov », et « Dec ». La valeur renvoyée pointe sur une chaîne statique qui sera écrasée à chaque appel de l'une des fonctions ci-dessus. La fonction renseigne également la variable externe tzname avec les informations concernant le fuseau horaire (voir tzset(3)).
La version réentrante ctime_r() effectue le même travail mais stocke la chaîne dans un tampon fourni par l'appelant, d'une longueur minimale de 26 caractères. Elle ne renseigne pas nécessairement tzname.
La fonction gmtime() convertit la date timep en une représentation struct tm exprimée en Temps Universel. Elle peut renvoyer NULL quand l'année ne tient pas dans un entier. La valeur renvoyée pointe vers une structure allouée statiquement qui peut être écrasée par une invocation ultérieure d'une fonction de date ou d'heure. La fonction réentrante gmtime_r() effectue le même travail mais stocke le résultat dans une structure fournie par l'appelant.
La fonction localtime() convertit la date timep en une représentation struct tm exprimée en fonction du fuseau horaire de l'utilisateur. Cette fonction se comporte comme si elle appelait tzset(3) et renseigne les variables externes tzname avec les informations concernant le fuseau horaire, timezone avec la différence (en secondes) entre Temps Universel et Temps Local, et daylight avec une valeur non nulle si le décalage horaire saisonnier s'applique. La valeur renvoyée pointe vers une structure allouée statiquement qui peut être écrasée par une invocation ultérieure d'une fonction de date ou d'heure. La fonction réentrante localtime_r() effectue le même travail mais stocke le résultat dans une structure fournie par l'appelant.
La fonction asctime() convertit la date tm exprimée sous forme struct tm en une chaîne de caractères du même format que ctime(). La valeur renvoyée pointe sur une chaîne statique qui sera écrasée à chaque appel de l'une des fonctions ci-dessus. La version réentrante asctime_r() effectue le même travail mais stocke la chaîne dans un tampon fourni par l'appelant, d'une longueur minimale de 26 caractères.
La fonction mktime() convertit la date timeptr exprimée sous forme struct tm en une date locale sous forme time_t. La fonction ignore les valeurs transmises des membres tm_wday tm_yday de la structure, et les recalcule en utilisant les autres membres. Si des membres de la structure débordent de l'intervalle autorisé, ils seront corrigés (par exemple le 40 Octobre devient le 9 Novembre). L'appel de mktime() renseigne également la variable externe tzname avec les informations concernant le fuseau horaire. Si la structure transmise ne peut pas être convertie, mktime() renvoie la valeur (time_t) -1 et ne modifie pas les membres tm_wday et tm_yday.
POSIX.1-2001 indique : « Les fonctions asctime(), ctime(), gmtime() et localtime() retourneront les valeurs dans l'un des deux objets statiques : une structure de temps détraquée et un tableau de type char. L'exécution de n'importe laquelle de ces fonctions peut écraser l'information renvoyée dans l'un ou l'autre de ces objets par n'importe quelle autre fonction. » cela peut arriver dans l'implémentation de la glibc.
Dans beaucoup d'implémentations, incluant la glibc, un 0 dans tm_mday est interprété comme étant le dernier jour du mois précédent.
La version glibc de la struct tm a des champs supplémentaires :
long tm_gmtoff; /* Secondes vers l'Est du temps TU */ const char *tm_zone; /* Abréviation du nom de fuseau */
présents quand _BSD_SOURCE est définiE avant l'inclusion de <time.h>. Ceci est une extension BSD, présente dans 4.3BSD-Reno.
Comformément à POSIX.1-2004, localtime() est doit se comporter comme si tzset() était appelée alors que localtime_r() n'a pas ce pré-requis. Dans un code portable tzset() devrait être appelé avant localtime_r().
Ce document est une traduction réalisée par Christophe Blaess <http://www.blaess.fr/christophe/> le 23 octobre 1996 et révisée le 17 juillet 2008.
L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 3 ctime ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.
Dernière mise à jour : 17 juillet 2008