STRPTIME
Section : Manuel du programmeur Linux (
3)
Mise à jour de la version anglaise : 12 novembre 2001
Index
Menu principal
NOM
strptime - Conversion d'une chaîne de date en une structure tm
SYNOPSIS
#define _XOPEN_SOURCE /* Pour glibc2 */
#include <time.h>
char *strptime(const char *s, const char *format,
struct tm *tm);
DESCRIPTION
La fonction
strptime()
est complémentaire de la fonction
strftime(3).
Elle convertit la chaîne de caractères pointée par
buf
en une valeur qui est stockée dans la structure
tm
pointée par l'argument
tm,
la conversion étant réalisée en suivant les indications
contenues dans la chaîne
format.
Cette dernière contient des descripteurs de champs et du texte, rappelant
scanf(3).
Chaque descripteur consiste en un caractère
%
suivi d'un second caractère indiquant le champ à interpréter.
Tous les autres sont considérés comme du texte, qui doit être présent
dans la chaîne fournie en entrée.
Toutefois une espace blanche se trouvant dans la chaîne de format
peut être mise en correspondance avec zéro ou plusieurs espaces.
Il devrait toujours y avoir une espace ou un autre caractère
alphanumérique entre deux descripteurs de champs.
La fonction
strptime()
traite la chaîne d'entrée de gauche à droite.
Les trois types d'éléments d'entrée possibles
(espace, caractère littéral, conversion)
sont manipulés l'un après l'autre.
Si l'entrée ne peut pas être mise en correspondance
avec la chaîne de format, la fonction s'arrête.
Le reste du format et de la chaîne d'entrée ne sont pas traités.
Les descripteurs applicables sont décrits ci-dessous.
Dans le cas d'une chaîne de caractères (comme un nom de jour ou de mois),
la comparaison ne tient pas compte des majuscules/minuscules.
Dans le cas d'un nombre, les zéros au début sont autorisés
mais pas obligatoires.
- %%
-
Le caractère
%
- %a ou %A
-
Le jour de la semaine en utilisant
les noms correspondants à la localisation.
Les noms abrégés ou entiers peuvent être utilisés.
- %b ou %B ou %h
-
Le mois en utilisant les noms correspondants à la localisation.
Les noms abrégés ou entiers peuvent être utilisés.
- %c
-
La date et l'heure en utilisant le format de la localisation.
- %C
-
Le numéro de siècle (0-99).
- %d ou %e
-
Le jour du mois (1-31)
- %D
-
La date, ainsi : %m/%d/%y.
C'est la date au format américain, très gênante pour les autres pays,
notamment l'Europe qui utilise une notation
%d/%m/%y.
Le format standard ISO 8601 est
%Y-%m-%d.
- %H
-
L'heure (0-23)
- %I
-
L'heure (0-12)
- %j
-
Le numéro du jour dans l'année (001-366)
- %m
-
Le numéro du mois (1-12)
- %M
-
La minute (0-59)
- %n
-
Un espace blanc quelconque
- %p
-
Équivalent local de AM ou PM (éventuellement rien).
- %r
-
L'heure sur 12 heures avec l'équivalent local de AM ou PM.
Dans la localisation POSIX, équivalent à
%I:%M:%S %p.
Si le champ
t_fmt_ampm
de la catégorie
LC_TIME
de la localisation est vide, le comportement est indéfini.
- %R
-
Équivalent à :
%H:%M.
- %S
-
Les secondes (0-61, des secondes de rattrapages sont autorisées).
- %t
-
Un espace blanc quelconque.
- %T
-
Équivalent de
%H:%M:%S.
- %U
-
Le numéro de semaine (0-53), le premier dimanche de janvier
étant le premier jour de la semaine 1.
- %w
-
Le numéro du jour dans la semaine (0-6), en commençant le dimanche.
- %W
-
Le numéro de semaine (0-53), le premier lundi de janvier
étant le premier jour de la semaine 1.
- %x
-
la date, en utilisant le format usuel de la localisation.
- %X
-
l'heure, en utilisant le format usuel de la localisation.
- %y
-
l'année sans le siècle (0-99; les zéros au début sont autorisés
mais pas obligatoires).
Lorsque le siècle n'est pas indiqué par une autre conversion, les années
69 à 99 sont considérées comme étant du vingtième siècle (1969 à 1999),
et les années 00-68 du vingt-et-unième siècle (2000-2068).
- %Y
-
L'année en incluant le siècle (par exemple, 1996)
Certains descripteurs peuvent être complétés par les caractères
modificateurs E et O, indiquant qu'il faut employer un autre format
ou une autre spécification.
Si cet autre format, ou cette autre conversion n'est pas disponible
dans la localisation en cours, le descripteur n'est pas modifié.
Le modificateur E indique que la chaîne d'entrée peut contenir
des versions différentes de la date et l'heure,
en fonction de la localisation :
- %Ec
-
Une représentation différente de la date et l'heure.
- %EC
-
Le nom de l'année de base (période) dans la représentation
locale alternative.
- %Ex
-
Une autre représentation de la date.
- %EX
-
Une autre représentation de l'heure.
- %Ey
-
Le décalage (en année) par rapport à l'année
%EC
dans la représentation locale alternative.
- %EY
-
La représentation complète de l'année.
Le modificateur O indique que les saisies numériques peuvent être
effectuées dans un format différent, dépendant de la localisation.
- %Od ou %Oe
-
Le jour du mois.
Les zéros en tête sont permis mais pas obligatoires.
- %OH
-
L'heure (sur 24 heures).
- %OI
-
L'heure (sur 12 heures).
- %Om
-
Le numéro du mois.
- %OM
-
Les minutes.
- %OS
-
Les secondes.
- %OU
-
Le numéro de la semaine.
- %Ow
-
Numéro du jour dans la semaine, le dimanche étant zéro.
- %OW
-
Le numéro du jour de la semaine, en commençant le lundi.
- %Oy
-
L'année (ou décalage par rapport à
%C)
en utilisant les symboles numériques régionaux.
Les champs de la structure
tm
définie dans
<time.h>
sont :
struct tm
{
int tm_sec; /* secondes */
int tm_min; /* minutes */
int tm_hour; /* heures */
int tm_mday; /* jour du mois */
int tm_mon; /* mois */
int tm_year; /* année */
int tm_wday; /* jour de la semaine */
int tm_yday; /* jour de l'année */
int tm_isdst; /* décalage été/hiver */
};
VALEUR RENVOYÉE
La fonction
strptime()
renvoie un pointeur sur le premier caractère de la chaîne
buf
n'ayant pas été traité.
Dans le cas où la chaîne de saisie est plus longue que ce que réclame
le format, la valeur renvoyée pointe juste après le dernier
caractère d'entrée ayant été analysé.
Si toute la chaîne a été traitée,
le pointeur est dirigé sur l'octet nul en fin de chaîne.
Si
strptime()
n'arrive pas à effectuer toutes les conversions, il renvoie NULL.
CONFORMITÉ
SUSv2, POSIX.1-2001.
NOTES
En principe cette fonction n'initialise pas
tm,
mais n'y stocke que les valeurs lues.
Ceci signifie que le contenu de
tm
doit être initialisé avant l'appel.
Les détails diffèrent suivant les systèmes Unix.
L'implémentation de la glibc ne modifie pas les champs
non mentionnés explicitement, sauf
tm_wday,
et
tm_yday
qui sont recalculés si un champ d'année, de mois ou de jour est modifié.
Cette fonction n'est disponible que dans les versions de bibliothèque
depuis la 4.6.8.
Les bibliothèques Linux libc4 et libc5 incluaient toujours le prototype
de cette fonction, la bibliothèque glibc 2 ne fournit le prototype
que si les constantes
_XOPEN_SOURCE
ou
_GNU_SOURCE
sont définies.
Avant la libc 5.4.13, les espaces (et les conversions « n » et « t »)
n'étaient pas gérées ; les caractères de modification locale « E » et
« O » n'étaient pas acceptés ; et la spécification « C » était
un synonyme pour « c ».
La conversion « y » (année dans le siècle) est toujours considérée
comme appartenant au vingtième siècle dans les libc4 et libc5.
Elle est prise dans l'intervalle 1950-2049 par la glibc 2.0,
et 1969-2068 par la glibc 2.1.
Notes glibc
Pour des raisons de symétrie, la glibc essaye d'offrir pour
strptime()
les mêmes caractères de formatage que ceux de
strftime(3).
(Dans la plupart des cas, les champs sont lus mais aucun membre de
tm
n'est modifié).
Ceci conduit à :
- %F
-
Équivalent à
%Y-%m-%d,
le format ISO 8601 pour la date.
- %g
-
L'année correspondant au numéro de semaine ISO, sans le siècle (0-99).
- %G
-
L'année correspondant au numéro de semaine ISO (par exemple 1991).
- %u
-
Le numéro du jour de la semaine (1-7, lundi valant 1).
- %V
-
Le numéro de semaine ISO 8601:1988 (1-53).
Si la semaine (commençant lundi) contenant le 1er janvier a quatre jours
ou plus de la nouvelle année, elle est comptée en semaine 1.
Sinon elle est considérée comme dernière semaine de l'année précédente,
et c'est la suivante qui est la semaine 1.
- %z
-
Spécification standard RFC-822/ISO 8601 pour le fuseau horaire.
- %Z
-
Le nom du fuseau horaire.
De même, à cause des extensions GNU de
strftime(3),
%k
est accepté en synonyme de
%H,
et
%l
est accepté comme synonyme de
%I,
et
%P
en synonyme de
%p.
Enfin,
- %s
-
Le nombre de secondes depuis le 1er janvier 1970 à Oh TU.
Les secondes de rattrapage ne sont pas comptées sauf si un support
spécifique est disponible.
L'implémentation de la glibc n'impose pas la présence
de caractères blancs entre deux descripteurs de champs.
EXEMPLE
L'exemple suivant montre l'utilisation de
strptime()
et
strftime(3).
#define _XOPEN_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <time.h>
int
main(void)
{
struct tm tm;
char buf[255];
strptime("2001-11-12 18:31:01", "%Y-%m-%d %H:%M:%S", &tm);
strftime(buf, sizeof(buf), "%d %b %Y %H:%M", &tm);
puts(buf);
exit(EXIT_SUCCESS);
}
VOIR AUSSI
time(2),
getdate(3),
scanf(3),
setlocale(3),
strftime(3),
feature_test_macros(7)
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 strptime ».
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
-
- CONFORMITÉ
-
- NOTES
-
- Notes glibc
-
- EXEMPLE
-
- VOIR AUSSI
-
- TRADUCTION
-
Dernière mise à jour : 17 juillet 2008