Provided by: manpages-fr-dev_3.65d1p1-1_all bug

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.

       La spécification de format est une chaîne terminée par un caractère nul, qui peut contenir des  séquences
       de  caractères  spéciales appelées spécifications de conversion, chacune commence par un character « % »,
       et se termine 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 le caractère nul) sont copiés tels quels
       depuis format dans s. Cependant, les caractères spécificateurs de conversion sont remplacés comme suit :

       %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  (consultez  %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 consultez %T.

       %s     Le nombre de secondes écoulées depuis l'époque, 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. Consultez 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. Consultez 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. Consultez aussi %U et %W. (SU)

       %w     Le numéro du jour de la semaine, sous forme décimale (0-6), dimanche valant 0. 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 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 (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). (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>. Consultez aussi ctime(3).

VALEUR RENVOYÉE

       Si  la  taille  de  la  chaîne de résultat ne dépasse pas max octets (caractère NUL compris), la fonction
       strftime() renvoie le nombre d'octets écrits dans le tableau s, sans compter l'octet  nul  final.  Si  la
       longueur  de la chaîne dépasse max octets (caractère NUL compris), 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. Une chaîne format vide renvoie aussi  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

       Si la chaîne de sortie dépasse max octets, errno n'est pas modifié. 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 aucune modification de errno pour strftime().

       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

       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"

   Programme 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("Result string is \"%s\"\n", outstr);
           exit(EXIT_SUCCESS);
       }

VOIR AUSSI

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

COLOPHON

       Cette page fait partie de la publication 3.65 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

       Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a <http://po4a.alioth.debian.org/> par
       l'équipe de traduction francophone au sein du projet perkamon <http://perkamon.alioth.debian.org/>.

       Christophe      Blaess      <http://www.blaess.fr/christophe/>      (1996-2003),       Alain       Portal
       <http://manpagesfr.free.fr/>  (2003-2006).  Nicolas  François  et  l'équipe  francophone de traduction de
       Debian (2006-2009).

       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> ».