STRFTIME
Section : Manuel du programmeur Linux (
3)
Mise à jour de la version anglaise : 23 novembre 2005
Index
Menu principal
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);
DESCRIPTION
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
spécifications de conversion
sont introduites par le caractère « % » et terminées par un
caractère spécificateur 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 de
%Y-%m-%d
(format de date ISO 8601). (C99)
- %G
-
L'année ISO 8601 avec le siècle comme nombre décimal.
L'année sur quatre chiffres correspond
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:1988 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,
et où lundi est le premier jour de la semaine.
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 s'applique depuis 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 le C ANSI (sans marque), celles indiquées par les Spécifications Single
Unix (marquées SU), celles fournies par le paquetage 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
Notes 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(1)
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);
}
Aujourd'hui,
gcc(1)
fournit l'option
-Wno-format-y2k
pour éviter l'avertissement, ainsi,
la solution de rechange ci-dessus n'est plus nécessaire.
EXEMPLE
Le programme suivant peut être utilisé pour expérimenter
strftime().
#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 */
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"
VOIR AUSSI
date(1),
time(2),
ctime(3),
setlocale(3),
sprintf(3),
strptime(3)
TRADUCTION
Ce document est une traduction réalisée par Christophe Blaess
<http://www.blaess.fr/christophe/> le 9 novembre 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 strftime ».
N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute
erreur dans cette page de manuel.
Index
- NOM
-
- SYNOPSIS
-
- DESCRIPTION
-
- VALEUR RENVOYÉE
-
- ENVIRONNEMENT
-
- CONFORMITÉ
-
- NOTES
-
- Notes glibc
-
- BOGUES
-
- EXEMPLE
-
- VOIR AUSSI
-
- TRADUCTION
-
Dernière mise à jour : 17 juillet 2008