NOM
strftime - Formater la date et l’heure
SYNOPSIS
#include <time.h>
size_t strftime(char *s, size_t max, const char *format,
const struct tm *tm);
La fonction strftime() formate les divers champs de la structure tm en
fonction de la chaîne de spécification format, puis place le résultat
dans la chaîne s de taille max.
Les caractères ordinaires présents dans la chaîne format seront
simplement copiés dans s. Les spcifications de conversion sont
introduites par le caractère « % » et terminées par un caractre
spcificateur de conversion, et sont remplacés dans la chaîne s ainsi :
%a Le nom abrégé du jour de la semaine, en fonction de la
localisation en cours.
%A Le nom complet du jour de la semaine, en fonction de la
localisation en cours.
%b Le nom abrégé du mois, en fonction de la localisation en cours.
%B Le nom complet du mois, en fonction de la localisation en cours.
%c La représentation classique de la date et de l’heure, suivant la
localisation en cours.
%C Le siècle (année/100) sous forme de nombre de deux chiffres.
(SU)
%d Le quantième du mois sous forme de nombre décimal (entre 01 et
31).
%D Équivalent à %m/%d/%y. Seulement pour les américains. Ces
derniers doivent noter que les autres pays préfèrent le format
%d/%m/%y. Dans un contexte international, ce format est ambigu
et doit être évité. (SU)
%e Comme %d, le quantième du mois sous forme décimal, mais
l’éventuel zéro en tête est remplacé par un espace. (SU)
%E Modificateur : utiliser un format de rechange. Voir plus bas.
(SU)
%F Équivalent à %Y-%m-%d (format de date ISO 8601). (C99)
%G L’année ISO 8601 basée sur les semaines (voir la section NOTES)
sous forme de nombre décimal, avec le siècle. L’année sur quatre
chiffres correspondant au numéro de la semaine ISO (voir %V).
C’est le même format que %Y, sauf que si le numéro de semaine
appartient à l’année suivante ou précédente, c’est celle-ci qui
est affichée à la place. (TZ)
%g Comme %G sans le siècle, c’est-à-dire avec une année sur deux
chiffres (00-99). (TZ)
%h Équivalent à %b. (SU)
%H L’heure, sur 24 heures, sous forme de nombre décimal (entre 00
et 23).
%I L’heure, sur 12 heures, sous forme de nombre décimal (entre 01
et 12).
%j Le numéro du jour dans l’année (entre 001 et 366).
%k L’heure (sur 24 heures) sous forme de nombre décimal (intervalle
0 à 23). Les chiffres uniques sont précédés d’un blanc (voir
aussi %H). (TZ).
%l L’heure (sur 12 heures) sous forme de nombre décimal (intervalle
1 à 12). Les chiffres uniques sont précédés d’un blanc (voir
aussi %I). (TZ).
%m Le numéro du mois (entre 01 et 12).
%M La minute, sous forme de nombre décimal (00 à 59).
%n Un caractère saut-de-ligne. (SU)
%O Modificateur : utiliser un format de rechange. Voir plus bas.
(SU)
%p L’une des deux chaînes « AM » ou « PM » en fonction de l’heure,
ou la traduction de ces chaînes en fonctions de la localisation
en cours. Midi est traité comme « PM » et minuit comme « AM ».
%P Comme %p mais en minuscule: « am » ou « pm » ou une chaîne
locale équivalente. (GNU)
%r L’heure en notation a.m. ou p.m. Dans la localisation POSIX,
c’est équivalent à %I:%M:%S %p. (SU)
%R L’heure en format 24 heures (%H:%M). (SU). Pour avoir les
secondes voir %T.
%s Le nombre de secondes écoulées depuis le 1er janvier 1970 à
00:00:00 UTC. (TZ).
%S La seconde, sous forme de nombre décimal (00-60). L’intervalle
peut être supérieur à 60 pour autoriser des secondes de
rattrapage.
%t Un caractère de tabulation. (SU)
%T L’heure en notation 24 heures (%H:%M:%S). (SU)
%u Le jour de la semaine sous forme décimal, de 1 (lundi) à 7. Voir
aussi %w. (SU)
%U Le numéro de la semaine dans l’année, sous forme de nombre
décimal (00-53), en commençant le comptage au premier dimanche
de l’année. Voir aussi %V et %W.
%V Le numéro de semaine ISO 8601 (voir la section NOTES) de l’année
en cours sous forme de nombre décimal dans l’intervalle 01-53,
où la semaine 1 est la première ayant au moins 4 jours dans
l’année en cours. Voir aussi %U et %W. (SU)
%w Le numéro du jour de la semaine, sous forme décimale (0-6),
dimanche valant 0. Voir aussi %u.
%W Le numéro de la semaine dans l’année, sous forme de nombre
décimal (00-53), en commençant le comptage au premier lundi de
l’année.
%x La représentation usuelle de la date, sans l’heure, dans la
localisation en cours.
%X La représentation usuelle de l’heure, sans la date, dans la
localisation en cours.
%y L’année, sous forme de nombre décimal, sans le siècle (entre 00
et 99).
%Y L’année, sous forme de nombre décimal, incluant le siècle.
%z Le fuseau horaire sous forme de décalage GMT. Nécessaire pour
créer des dates conformes à la RFC 822 (avec
"%a, %d %b %Y %H:%M:%S %z"). (GNU)
%Z Le nom ou l’abréviation du fuseau horaire.
%+ La date et l’heure au format date(1). (TZ) (Non supporté par la
glibc2)
%% Un caractère « % ».
Certaines spécifications de conversion peuvent être modifiées en
faisant précéder le caractère spécificateur de conversion par le
modificateur E ou O pour indiquer un format de rechange. Si le format
de rechange n’existe pas pour la localisation en cours, le comportement
ne sera pas modifié. Les spécifications Single Unix mentionnent %Ec,
%EC, %Ex, %EX, %Ey, %EY, %Od, %Oe, %OH, %OI, %Om, %OM, %OS, %Ou, %OU,
%OV, %Ow, %OW, %Oy, où l’action du modificateur O est d’utiliser un
autre format numérique (par exemple des chiffres romains), et l’action
de E est d’utiliser une représentation dépendant de la localisation.
Les champs de la structure tm sont définis dans <time.h>. Voir aussi
ctime(3).
VALEUR RENVOYÉE
La fonction strftime() renvoie le nombre de caractères écrits dans le
tableau s, sans compter l’octet nul final. Si la chaîne était trop
courte, strftime() renvoie 0, et le contenu de la chaîne est indéfini
(ce comportement est valable depuis au moins la libc 4.4.4, des
versions plus anciennes de la libc, comme la 4.4.1, renvoyaient max si
la chaîne était trop courte).
Remarquez qu’une valeur de retour nulle n’indique pas toujours une
erreur. Dans de nombreuses localisations, par exemple, %p renvoie une
chaîne vide.
ENVIRONNEMENT
Les variables d’environnement TZ et LC_TIME sont utilisées.
CONFORMITÉ
SVr4, C89, C99. Il y a une inclusion stricte entre les jeux de
conversions fournies par C ANSI (sans marque), celles indiquées par les
Spécifications Single Unix (marquées SU), celles fournies par le paquet
timezone d’Olson (marquées TZ), et celles de la glibc (marquées GNU),
sauf pour %+ qui n’est pas supporté par glibc2. D’un autre côté glibc2
offre plusieurs extensions. POSIX.1 ne traite que les conversions C
ANSI. POSIX.2 décrit à propos de date(1) plusieurs extensions
applicables également à strftime(). La conversion %F est dans C99 et
POSIX.1-2001.
Dans SUSv2, le %S spécifié permettait un intervalle de 00 à 61, pour
autoriser la possibilité théorique d’une minute incluant une double
seconde de rattrapage (il n’y a jamais eu de telle minute).
NOTES
Numéros des semaines ISO 8601
%G, %g et %V produisent des valeurs calculées sur la base des semaines
de l’année définies par la norme ISO 8601. Dans ce système, les
semaines démarrent le lundi et sont numérotées de 01, pour la première
semaine, jusqu’à 52 ou 53, pour la dernière semaine. La semaine 1 est
la première semaine pour laquelle au moins quatre jours sont dans
l’année (ce qui revient au même que de la définir comme la semaine du
premier jeudi de l’année ou la semaine du 4 janvier). Quand trois
jours, ou moins, se trouvent dans la première semaine calendaire de la
nouvelle année se trouvent dans cette année, alors le système de
numérotation des semaines de l’ISO 8601 place ces jours dans la semaine
53 de l’année précédente. Par exemple, le 1er janvier 2010 est un
vendredi, ce qui signifie que seulement 3 jours se trouvent dans la
semaine calendaire du début 2010. l’ISO 8601 considère donc ces jours
comme faisant partie de la semaine 53 (%V) de l’année 2009 (%G) ; la
semaine 01 de l’année 2010 pour l’ISO 8601 démarre le lundi 4 janvier
2010.
Notes sur la glibc
La glibc fournit des extensions pour les spécifications de conversion
(ces extensions ne sont pas spécifiées par POSIX.1-2001 mais quelques
autres systèmes fournissent des fonctionnalités similaires). Entre le
caractère «% » et le caractère spécificateur de conversion, on peut
spécifier un attribut optionnel et un champ largeur (ceux-ci précèdent
les modificateurs E ou 0 s’ils sont présents).
Les caractères attributs suivants sont autorisés :
_ (souligné) Compléter une chaîne de résultat numérique avec des
espaces.
- (tiret) Ne pas compléter une chaîne de résultat numérique.
0 Compléter une chaîne de résultat numérique avec des zéros même
si le caractère spécificateur de conversion utilise des espaces
par défaut.
^ Convertir une chaîne alphabétique en une chaîne résultante en
majuscule.
# Échanger la casse de la chaîne résultat (cet attribut ne
fonctionne qu’avec certains caractères spécificateurs de
conversion, et parmi ceux-ci, il n’est vraiment utile qu’avec
%Z).
Un spécificateur de largeur décimal optionnel peut suivre
l’(éventuellement absent) attribut. Si la taille naturelle du champ est
plus petite que cette largeur, la chaîne résultat sera alors complétée
(sur la gauche) jusqu’à la largeur spécifiée.
BOGUES
Certaines versions boguées de gcc se plaignent de l’utilisation de %c :
warning: %c yields only last 2 digits of year in some locales
(Attention : ne donne que les deux derniers chiffres de l’année dans
certaines localisations). Bien sûr, les programmeurs sont encouragés à
utiliser %c, cela donne la représentation préférée de date et d’heure.
Il y a eu des tas d’astuces bizarres pour éviter ce problème de gcc(1).
Une relativement propre est d’utiliser une fonction intermédiaire :
size_t
my_strftime(char *s, size_t max, const char *fmt,
const struct tm *tm)
{
return strftime(s, max, fmt, tm);
}
De nos jours, gcc(1) fournit une option -Wno-format-y2k pour éviter
l’avertissement, et la solution de contournement ci-dessus n’est plus
nécessaire.
EXEMPLE
Le programme suivant peut être utilisé pour expérimenter strftime().
Voici quelques exemples de la chaîne résultat produite par
l’implémentation glibc de strftime() :
$ ./a.out '%m'
La chaîne résultat est "11"
$ ./a.out '%5m'
La chaîne résultat est "00011"
$ ./a.out '%_5m'
La chaîne résultat est " 11"
Source du programme
#include <time.h>
#include <stdio.h>
#include <stdlib.h>
int
main(int argc, char *argv[])
{
char outstr[200];
time_t t;
struct tm *tmp;
t = time(NULL);
tmp = localtime(&t);
if (tmp == NULL) {
perror("localtime");
exit(EXIT_FAILURE);
}
if (strftime(outstr, sizeof(outstr), argv[1], tmp) == 0) {
fprintf(stderr, "strftime a renvoyé 0");
exit(EXIT_FAILURE);
}
printf("La chaîne résultat est \"%s\"\n", outstr);
exit(EXIT_SUCCESS);
} /* main */
VOIR AUSSI
date(1), time(2), ctime(3), setlocale(3), sprintf(3), strptime(3)
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 et mise à jour par Christophe
Blaess <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis 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 Nicolas François
<nicolas.francois@centraliens.net> 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> ».