strftime(3) Library Functions Manual strftime(3)

strftime - Formater la date et l'heure

Bibliothèque C standard (libc, -lc)

#include <time.h>
size_t strftime(char s[restrict .max], size_t max,
                const char *restrict format,
                const struct tm *restrict tm);
size_t strftime_l(char s[restrict .max], size_t max,
                const char *restrict format,
                const struct tm *restrict tm,
                locale_t locale);

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. Le détail de la structure tm est donné dans <time.h>. Consultez également ctime(3).

La spécification de format est une chaîne terminée par l’octet NULL, qui peut contenir des séquences de caractères spéciales appelées spécifications de conversion, chacune commençant par un caractère « % » et se terminant par un autre caractère, appelé caractère spécificateur de conversion. Toutes les autres séquences de caractères sont des séquences de caractères ordinaires.

Les caractères des séquences de caractères ordinaires (y compris l'octet NULL) sont copiés tels quels depuis format dans s. Cependant, les caractères indicateurs de conversion sont remplacés comme montré dans la liste ci-dessous. Dans cette liste, le(s) champ(s) de la structure tm employés sont également détaillés.

%a
Le nom abrégé du jour de la semaine en fonction de la localisation en cours, déterminé par tm_wday. Les noms spécifiques utilisés par chaque locale peuvent être obtenus par un appel à nl_langinfo(3) avec ABDAY_{1–7} comme argument.
%A
Le nom complet du jour de la semaine en fonction de la localisation en cours, déterminé par tm_wday. Les noms spécifiques utilisés la locale en cours peuvent être obtenus par un appel à nl_langinfo(3) avec DAY_{1–7} comme argument.
%b
Le nom du mois abrégé en fonction de la localisation en cours, déterminé par tm_mon. Les noms spécifiques utilisés par chaque locale peuvent être obtenus par un appel à nl_langinfo(3) avec ABMON_{1–12} comme argument.
%B
Le nom complet du mois en fonction de la localisation en cours, déterminé par tm_mon. Les noms spécifiques utilisés par chaque locale peuvent être obtenus par un appel à nl_langinfo(3) avec MON_{1–12} comme argument.
%c
La représentation usuelle de la date et de l'heure en fonction de la localisation en cours. Le formatage spécifique utilisé par la locale en cours peut être obtenu par un appel à nl_langinfo(3) avec D_T_FMT comme argument pour la spécification de conversion %c, et ERA_D_T_FMT pour la spécification de conversion %Ec. Cela est équivalent pour la locale POSIX à %a %b %e %H:%M:%S %Y.
%C
Le siècle (année/100) sous forme d'un nombre à deux chiffres, déterminé par tm_year (SU). L'indicateur de conversion %EC correspond au nom de l'ère.
%d
Le jour du mois sous forme de nombre décimal, entre 01 et 31, déterminé par tm_mday.
%D
Équivalent à %m/%d/%y. Uniquement 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 jour du mois sous forme décimale, déterminé par tm_day, mais l'éventuel zéro en tête est remplacé par une espace (SU).
%E
Modificateur : utiliser un format de rechange. Voir plus bas (SU).
%F
Equivalent to %Y-%m-%d (the ISO 8601 date format). (C99)
%G
The ISO 8601 week-based year (see NOTES) with century as a decimal number. The 4-digit year corresponding to the ISO week number (see %V). This has the same format and value as %Y, except that if the ISO week number belongs to the previous or next year, that year is used instead. (TZ) (Calculated from tm_year, tm_yday, and tm_wday.)
%g
Comme %G, mais sans le siècle, c'est-à-dire avec une année sur deux chiffres [00−99], déterminée par tm_year, tm_yday et tm_wday (TZ).
%h
Équivalent à %b (SU).
%H
L'heure, sur 24 heures, sous forme de nombre décimal (entre 00 et 23), déterminée par tm_hour.
%I
L'heure, sur 12 heures, sous forme de nombre décimal (entre 01 et 12), déterminée par tm_hour.
%j
Le numéro du jour dans l'année (entre 001 et 366), déterminée par tm_day.
%k
L'heure (sur 24 heures) sous forme de nombre décimal (intervalle 0 à 23) ; les chiffres uniques étant précédés d'un blanc (voir aussi %H), déterminée par tm_hour (TZ).
%l
L'heure (sur 12 heures) sous forme de nombre décimal (intervalle 1 à 12), les chiffres uniques étant précédés d'un blanc (voir aussi %I), déterminée par tm_hour (TZ).
%m
Le numéro du mois (entre 01 et 12), déterminé par tm_mon.
%M
La minute, sous forme de nombre décimal (de 00 à 59), déterminée par tm_min.
%n
Un caractère de saut de ligne (SU).
%O
Modificateur : utiliser des symboles numériques alternatifs. Voir plus bas (SU).
%p
L'une des deux chaînes « AM » ou « PM » en fonction de l'heure, déterminée par tm_hour, ou la traduction de ces chaînes en fonction de la localisation en cours. Midi est traité comme « PM » et minuit comme « AM ». La représentation textuelle des chaînes « AM » et « PM » spécifique à la locale en cours peut être obtenue par un appel à nl_langinfo(3) avec AM_STR ou PM_STR comme argument respectif.
%P
Comme %p mais en minuscule : « am » ou « pm » ou une chaîne locale équivalente, déterminée par tm_hour (GNU).
%r
L'heure au format 12 heures (SU). Le format utilisé par la locale courante peut être obtenu en appelant nl_langinfo(3) avec T_FMT_AMPM comme argument. Dans la locale POSIX, cela est équivalent à %I:%M:%S %p.
%R
L'heure au format 24 heures, %H:%M (SU). Pour avoir les secondes consultez %T.
%s
Le nombre de secondes écoulées depuis l'Époque, 1er janvier 1970 à 00:00:00 UTC, déterminé par mktime(tm) (TZ).
%S
La seconde, sous forme de nombre décimal (entre 00 et 60), l'intervalle pouvant être supérieur à 60 pour autoriser des secondes de rattrapage, déterminée par tm_sec.
%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écimale, de 1 (lundi) à 7, déterminé par tm_wday. Consultez aussi %w (SU).
%U
Le numéro de la semaine dans l'année, sous forme de nombre décimal entre 00 et 53, en commençant le comptage au premier dimanche de l'année, déterminé par tm_yday et tm_wday. Consultez aussi %V et %W.
%V
The ISO 8601 week number (see NOTES) of the current year as a decimal number, range 01 to 53, where week 1 is the first week that has at least 4 days in the new year. See also %U and %W. (Calculated from tm_year, tm_yday, and tm_wday.) (SU)
%w
Le numéro du jour de la semaine, sous forme décimale dans l'intervalle 0−6, dimanche valant 0, déterminé par tm_wday. Consultez aussi %u.
%W
Le numéro de la semaine dans l'année, sous forme de nombre décimal (00−53), en commençant avec le premier lundi comme premier jour de la semaine 01, déterminé par tm_yday et tm_wday.
%x
La représentation usuelle de la date sans l'heure pour la locale en cours. Le format spécifique à la locale en cours peut être obtenu par un appel à nl_langinfo(3) avec D_FMT comme argument pour l'indicateur de conversion %x et ERA_D_FMT pour l'indicateur de conversion %Ex. Cela est équivalent à %m/%d/%y dans la locale POSIX.
%X
La représentation usuelle de l'heure sans la date pour la locale en cours. Le format spécifique à la locale en cours peut être obtenu par un appel à nl_langinfo(3) avec T_FMT comme argument pour l'indicateur de conversion %X et ERA_T_FMT pour l'indicateur de conversion %EX. Cela est équivalent à %H:%M:%S dans la locale POSIX.
%y
L'année, sous forme de nombre décimal, sans le siècle (comprise entre 00 et 99), déterminée par tm_year. L'indicateur de conversion %Ey correspond à l'année depuis le début de l'ère, désignée par l'indicateur de conversion %EC.
%Y
L'année, sous forme de nombre décimal, incluant le siècle, déterminée par tm_year. L'indicateur de conversion %EY correspond à la représentation alternative complète d'une année.
%z
Le fuseau horaire (c'est-à-dire le décalage en heures et minutes par rapport à UTC) sous forme numérique +hhmm ou -hhmm (SU).
%Z
Le nom ou l'abréviation du fuseau horaire.
%+
La date et l'heure au format date(1), non pris en charge par la glibc2 (TZ).
%%
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 (SU) 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épendante de la localisation. Les règles encadrant la représentation des dates avec l'indicateur E peuvent être obtenues par un appel à nl_langinfo(3) avec ERA pour argument. Un exemple d'une telle forme alternative est le schéma de calendrier d'ère japonais dans la locale ja_JP de la glibc.

LA fonction strftime_l() est équivalente à strftime(), à part qu'elle utilise la localisation locale spécifiée à la place de la locale en cours. Le comportement est indéfini si locale n'est pas valable ou est LC_GLOBAL_LOCALE.

Si la taille de la chaîne de résultat ne dépasse pas max octets (octet NULL compris), la fonction strftime() renvoie le nombre d'octets écrits dans le tableau s, sans compter l'octet NULL final. Si la longueur de la chaîne dépasse max octets (octet NULL compris), strftime() renvoie 0 et le contenu de la chaîne est indéfini.

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. Une chaîne format vide renvoie aussi une chaîne vide.

Les variables d'environnement TZ et LC_TIME sont utilisées.

Pour une explication des termes utilisés dans cette section, consulter attributes(7).

Interface Attribut Valeur
strftime(), strftime_l() Sécurité des threads MT-Safe env locale

C11, POSIX.1-2008.
POSIX.1-2008.

SVr4, C89.
POSIX.1-2008.

Il y a une inclusion stricte entre les jeux de conversions fournies par ANSI C (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 pris en charge par la glibc2. D'un autre côté glibc2 offre plusieurs extensions. POSIX.1 ne traite que les conversions ANSI C. 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).

%G, %g, and %V yield values calculated from the week-based year defined by the ISO 8601 standard. In this system, weeks start on a Monday, and are numbered from 01, for the first week, up to 52 or 53, for the last week. Week 1 is the first week where four or more days fall within the new year (or, synonymously, week 01 is: the first week of the year that contains a Thursday; or, the week that has 4 January in it). When three or fewer days of the first calendar week of the new year fall within that year, then the ISO 8601 week-based system counts those days as part of week 52 or 53 of the preceding year. For example, 1 January 2010 is a Friday, meaning that just three days of that calendar week fall in 2010. Thus, the ISO 8601 week-based system considers these days to be part of week 53 (%V) of the year 2009 (%G); week 01 of ISO 8601 year 2010 starts on Monday, 4 January 2010. Similarly, the first two days of January 2011 are considered to be part of week 52 of the year 2010.

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.

Si la chaîne de sortie dépasse max octets, errno n'est pas défini. Cela empêche de distinguer ce cas d'erreur des cas où la chaîne format aurait légitimement produit une chaîne de sortie de longueur nulle. POSIX.1-2001 ne spécifie aucun réglage de errno pour strftime().

Certaines versions boguées de gcc(1) se plaignent de l'utilisation de %c : avertissement : `%c' laisse seulement les 2 derniers chiffres de l'année dans certaines configurations linguistiques . Bien sûr, les programmeurs sont encouragés à utiliser %c, car 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.

format de date compatible RFC 2822 (avec des paramètres régionaux en anglais pour %a et %b)


"%a, %d %b %Y %T %z"

format de date compatible RFC 822 (avec des paramètres régionaux en anglais pour %a et %b)


"%a, %d %b %y %T %z"

Le programme suivant peut être utilisé pour expérimenter strftime().

Voici quelques exemples de la chaîne résultat produite par l'implémentation de strftime() dans la glibc :


$ ./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"

#include <stdio.h>
#include <stdlib.h>
#include <time.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 returned 0");
        exit(EXIT_FAILURE);
    }
    printf("Result string is \"%s\"\n", outstr);
    exit(EXIT_SUCCESS);
}

date(1), time(2), ctime(3), nl_langinfo(3), setlocale(3), sprintf(3), strptime(3)

La traduction française de cette page de manuel a été créée par Christophe Blaess https://www.blaess.fr/christophe/, Stéphan Rafin <stephan.rafin@laposte.net>, Thierry Vignaud <tvignaud@mandriva.com>, François Micaux, Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard <fevrier@tigreraye.org>, Jean-Luc Coulon (f5ibh) <jean-luc.coulon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@debian.org>, David Prévot <david@tilapin.org> et Grégoire Scano <gregoire.scano@malloc.fr>

Cette traduction est une documentation libre ; veuillez vous reporter à la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message à debian-l10n-french@lists.debian.org.

28 janvier 2024 Pages du manuel de Linux 6.06