Provided by:
manpages-fr_1.67.0-1_all 
NOM
ctime, asctime, gmtime, localtime, mktime, asctime_r, ctime_r,
gmtime_r, localtime_r - Conversions de dates et heures binaires en
ASCII.
SYNOPSIS
#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);
DESCRIPTION
Les fonctions ctime(), gmtime() et localtime() prennent toutes un
argument de type time_t qui représente une date. Si l’on interprète
cet argument comme une valeur absolue, il s’agit du nombre de secondes
écoulées depuis le 1er Janvier 1970 à 00h 00m 00s en Temps Universel
(TU).
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> ainsi :
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 :
tm_sec Le nombre de secondes écoulées depuis le dernier changement de
minute. Normalement dans l’intervalle 0 à 59, ce membre peut
aller jusqu’à 61 durant les secondes de rattrapage périodique.
tm_min Le nombre de minutes écoulées depuis le dernier changement
d’heure, dans l’intervalle 0 à 59.
tm_hour
Le nombre d’heures écoulées depuis Minuit, dans l’intervalle 0 à
23.
tm_mday
Le quantième du mois, dans l’intervalle 1 à 31.
tm_mon Le nombre de mois écoulés depuis le début de l’année, dans
l’intervalle 0 à 11.
tm_year
Le nombre d’années écoulées depuis 1900.
tm_wday
Le nombre de jours écoulés depuis Dimanche, dans l’intervalle 0
à 6.
tm_yday
Le nombre de jours écoulés depuis le 1er Janvier, dans
l’intervalle 0 à 365 (0 à 364 si l’année n’est pas bissextile).
tm_isdst
Un drapeau indiquant si le décalage d’heure hiver/été est en
cours au moment de l’appel. La valeur retournée est positive si
le décalage est en fonction, nulle s’il ne l’est pas, et
négative si l’information n’est pas disponible.
L’appel ctime(t) est équivalent à asctime(localtime(t)). Il convertit
la date t en une chaîne de caractères de la forme
"Wed Jun 30 21:49:08 1993\n"
L’internationalisation de la date est possible en utilisant la fonction
setlocale(3) et strftime(3).
Les abréviations pour les jours de la semaine sont « Sun », « Mon »,
« Tue », « Wed », « Thu », « Fri », et « Sat ». Les abréviations pour
les 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 buffer 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 buffer 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 et 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.
VALEUR RENVOYÉE
Chacune de ces fonctions renvoie la valeur décrite plus haut, ou NULL
(-1 dans le cas de mktime()) si une erreur est détectée.
NOTES
Les quatre fonctions asctime(), ctime(), gmtime() et localtime()
renvoient un pointeur vers des données statiques et ne sont donc pas
sûres dans un contexte multi-threads. Les versions réentrantes
asctime_r(), ctime_r(), gmtime_r() et localtime_r() sont mentionnées
dans SUSv2, et disponibles depuis la libc 5.2.5.
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éfini avant l’inclusion de <time.h>.
Ceci est une extension BSD, présente dans 4.3BSD-Reno.
CONFORMITÉ
SVID 3, POSIX, BSD 4.3, ISO 9899
VOIR AUSSI
date(1), gettimeofday(2), newctime(3), time(2), utime(2), clock(2),
difftime(3), strftime(3), strptime(3), tzset(3)
TRADUCTION
Christophe Blaess, 1996-2003.