NOM
getdate, getdate_r - Conversion d’un temps sous forme de chaîne de
caractères au format humain
SYNOPSIS
#define _XOPEN_SOURCE 500
#include <time.h>
struct tm *getdate(const char *string);
extern int getdate_err;
#define _GNU_SOURCE
#include <time.h>
int getdate_r(const char *string, struct tm *res);
La fonction getdate() convertit une date et un temps sous forme de
chaîne de caractères, contenue dans le tampon string, au format humain.
Le temps au format humain est sauvegardé dans une structure tm et un
pointeur vers cette structure est renvoyé. Cette structure est allouée
statiquement, elle sera donc écrasée lors d’un prochain appel.
Contrairement à strptime(3), (qui a un argument format), getdate()
utilise les formats présents dans le fichier dont le chemin d’accès
complet est donné par la variable d’environnement DATEMSK. La première
ligne du fichier qui peut être mise en correspondance avec la chaîne
passée en paramètre est utilisée pour la conversion.
La correspondance n’est pas sensible à la casse. Les espaces superflus,
qu’ils soient dans le motif ou dans la chaîne à convertir, sont
ignorés.
Les paramètres de conversion qu’un motif peut contenir sont les mêmes
que pour strptime(3). Un indicateur de conversion supplémentaire est
spécifié dans POSIX.1-2001 :
%Z Nom du fuseaux horaire (non implémenté dans le glibc).
Lorsque %Z est spécifié, la structure contenant le temps au format
humain est initialisée avec le temps actuel du fuseaux horaire. Sinon,
elle est initialisée sous forme humaine à l’heure locale (comme lors
d’un appel à localtime(3)).
Lorsque seul le jour de la semaine est donné, le jour pris en compte
sera le premier jour correspondant à partir d’aujourd’hui inclus.
Lorsque seul le mois est spécifié (et pas l’année), le mois pris en
compte est le premier mois correspondant à partir du mois courant
inclus. Si aucun jour n’est indiqué, le premier jour du mois est pris
par défaut.
Lorsque les heures, minutes et secondes ne sont pas indiquées, l’heure
courante (heures, minutes et secondes) est prise par défaut.
Si aucune date n’est indiquée, mais que l’on connaît l’heure, l’heure
prise en compte sera la première occurrence de cette heure, à partir de
l’heure courante incluse.
getdate_r est une extension GNU qui fournit une version ré-entrante de
getdate. Au lieu d’utiliser une variable globale pour rapporter les
erreurs et un tampon statique pour renvoyer le temps au format humain,
elle renvoie les erreurs avec la valeur de retour de la fonction et le
temps au format humain dans le tampon alloué par l’appelant pointé par
res.
VALEUR RENVOYÉE
En cas de succès, getdate() renvoie un pointeur vers une structure
struct tm. Sinon elle renvoie NULL et positionne la variable globale
getdate_err avec l’un des codes d’erreur ci-dessous. La modification
éventuelle de errno est indéfinie.
En cas de succès, getdate_r() renvoie 0. En cas d’erreur, elle renvoie
l’un des codes d’erreur ci-dessous.
ERREURS
Les erreurs suivantes sont renvoyées par getdate_err (pour getdate())
ou par le code de retour de la fonction (pour getdate_r()).
1 La variable d’environnement DATEMSK est non définie ou sa valeur
est une chaîne vide.
2 Le fichier de modèle spécifié par DATEMSK ne peut être ouvert en
lecture.
3 Impossible de lire l’état du fichier.
4 Le fichier de modèle n’est pas un fichier régulier.
5 Une erreur est survenue au cours de la lecture du fichier de
modèle.
6 Échec d’allocation mémoire (pas assez de mémoire disponible).
7 Il n’y a pas de ligne dans le fichier qui puisse être mise en
correspondance avec l’entrée.
8 Paramètres d’entrée invalides.
ENVIRONNEMENT
DATEMSK
Fichier contenant les motifs de formatage.
TZ, LC_TIME
Variables utilisées par strptime(3).
CONFORMITÉ
POSIX.1-2001.
NOTES
La spécification POSIX.1-2001 pour strptime(3) contient des
spécifications de conversion utilisant les modificateurs %E ou %O alors
que de tels modificateurs ne sont pas indiqués pour getdate(). Dans la
glibc, getdate() est implémentée avec strptime(3), si bien que les deux
fonctions supportent exactement les mêmes conversions.
EXEMPLE
Le programme ci-dessous appelle getdate() pour chaque argument de la
ligne de commande et affiche la valeur des champs de la structure tm
renvoyée. La session shell suivante montre des exemples d’utilisation
de ce programme :
$ TFILE=$PWD/tfile
$ echo '%A' > $TFILE # Full weekday name
$ echo '%T' >> $TFILE # ISO date (YYYY-MM-DD)
$ echo '%F' >> $TFILE # Time (HH:MM:SS)
$ date
$ export DATEMSK=$TFILE
$ ./a.out Tuesday '2009-12-28' '12:22:33'
Sun Sep 7 06:03:36 CEST 2008
Call 1 ("Tuesday") succeeded:
tm_sec = 36
tm_min = 3
tm_hour = 6
tm_mday = 9
tm_mon = 8
tm_year = 108
tm_wday = 2
tm_yday = 252
tm_isdst = 1
Call 2 ("2009-12-28") succeeded:
tm_sec = 36
tm_min = 3
tm_hour = 6
tm_mday = 28
tm_mon = 11
tm_year = 109
tm_wday = 1
tm_yday = 361
tm_isdst = 0
Call 3 ("12:22:33") succeeded:
tm_sec = 33
tm_min = 22
tm_hour = 12
tm_mday = 7
tm_mon = 8
tm_year = 108
tm_wday = 0
tm_yday = 250
tm_isdst = 1
Source du programme
#define _GNU_SOURCE 500
#include <time.h>
#include <stdio.h>
#include <stdlib.h>
int
main(int argc, char *argv[])
{
struct tm *tmp;
int j;
for (j = 1; j < argc; j++) {
tmp = getdate(argv[j]);
if (tmp == NULL) {
printf("Call %d failed; getdate_err = %d\n",
j, getdate_err);
continue;
}
printf("Call %d (\"%s\") succeeded:\n", j, argv[j]);
printf(" tm_sec = %d\n", tmp->tm_sec);
printf(" tm_min = %d\n", tmp->tm_min);
printf(" tm_hour = %d\n", tmp->tm_hour);
printf(" tm_mday = %d\n", tmp->tm_mday);
printf(" tm_mon = %d\n", tmp->tm_mon);
printf(" tm_year = %d\n", tmp->tm_year);
printf(" tm_wday = %d\n", tmp->tm_wday);
printf(" tm_yday = %d\n", tmp->tm_yday);
printf(" tm_isdst = %d\n", tmp->tm_isdst);
}
exit(EXIT_SUCCESS);
}
VOIR AUSSI
time(2), localtime(3), setlocale(3), strftime(3), strptime(3),
feature_test_macros(7)
COLOPHON
Cette page fait partie de la publication 3.23 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent être trouvées à l’adresse
http://www.kernel.org/doc/man-pages/.
TRADUCTION
Cette page de manuel a été traduite par Stéphan Rafin <stephan DOT
rafin AT laposte DOT net> en 2002, puis a été mise à jour par Alain
Portal <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et mise à
disposition sur http://manpagesfr.free.fr/.
Les mises à jour et corrections de la version présente dans Debian sont
directement gérées par Florentin Duneau <fduneau@gmail.com> et l’équipe
francophone de traduction de Debian.
Veuillez signaler toute erreur de traduction en écrivant à
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir accès à la version anglaise de ce document
en utilisant la commande « man -L C <section> <page_de_man> ».
7 septembre 2008