Partager via


asctime_s, _wasctime_s

Convertissent une structure de temps tm en une chaîne de caractères. Ces fonctions sont des versions de asctime, _wasctime avec des améliorations de sécurité, comme indiqué dans Fonctionnalités de sécurité dans le CRT.

Syntaxe

errno_t asctime_s(
   char* buffer,
   size_t numberOfElements,
   const struct tm *tmSource
);
errno_t _wasctime_s(
   wchar_t* buffer,
   size_t numberOfElements
   const struct tm *tmSource
);
template <size_t size>
errno_t asctime_s(
   char (&buffer)[size],
   const struct tm *tmSource
); // C++ only
template <size_t size>
errno_t _wasctime_s(
   wchar_t (&buffer)[size],
   const struct tm *tmSource
); // C++ only

Paramètres

buffer
Pointeur vers une mémoire tampon pour stocker le résultat de la chaîne de caractères. Ce pointeur est supposé désigner un emplacement de mémoire valide dont la taille est spécifiée par numberOfElements.

numberOfElements
Taille de la mémoire tampon utilisée pour stocker le résultat.

tmSource
Structure date/heure. Cette fonction suppose un pointeur désignant un objet struct tm valide.

Valeur retournée

Zéro si l’opération aboutit. En cas d’échec, le gestionnaire de paramètres non valide est appelé, comme décrit dans la validation des paramètres. Si l’exécution est autorisée à se poursuivre, la valeur de retour est un code d’erreur. Les codes d’erreur sont définis dans ERRNO.H. Pour plus d’informations, consultez errno les constantes. Les codes d’erreur retournés pour chaque condition d’erreur sont répertoriés dans le tableau suivant.

Conditions d’erreur

buffer numberOfElements tmSource Retour Valeur dans buffer
NULL Quelconque Quelconque EINVAL Non modifié
Pas NULL (pointe vers une mémoire valide) 0 Tout EINVAL Non modifié
Pas NULL 0<numberOfElements< 26 Tout EINVAL Chaîne vide
Pas NULL >= 26 NULL EINVAL Chaîne vide
Pas NULL >= 26 Structure de temps non valide ou hors de la plage de valeurs pour les composants de temps EINVAL Chaîne vide

Remarque

Les conditions d’erreur pour wasctime_s sont similaires à asctime_s, à la différence que la limite de taille est mesurée en mots.

Notes

La fonction asctime convertit une valeur de temps stockée en tant que structure en une chaîne de caractères. La tmSource valeur est généralement obtenue à partir d’un appel à gmtime ou localtime. Les deux fonctions peuvent être utilisées pour renseigner une structure tm, comme défini dans TIME.H.

Membre de timeptr Valeur
tm_hour Heures depuis minuit (0-23)
tm_isdst Positif si l’heure d’été est en vigueur ; 0 si l’heure d’été n’est pas en vigueur ; négatif si l’état de l’heure d’été est inconnu. La bibliothèque runtime C suppose que les règles de calcul de l’heure d’été sont celles des États-Unis.
tm_mday Jour du mois (1 à 31)
tm_min Minutes après l’heure (0-59)
tm_mon Mois (0-11 ; Janvier = 0)
tm_sec Secondes après minute (0-59)
tm_wday Jour de la semaine (0-6 ; Dimanche = 0)
tm_yday Jour de l’année (0-365 ; 1er janvier = 0)
tm_year Année (année en cours moins 1900)

La chaîne de caractères convertie est également ajustée en fonction des paramètres de fuseau horaire local. Pour plus d’informations sur la configuration de l’heure locale, consultez les fonctions , _time32_time64timelocaltime_s_ftime32_ftime64_ftimeet , . _localtime32_s_localtime64_s Pour plus d’informations sur la définition de l’environnement de fuseau horaire et des variables globales, consultez _tzset.

Le résultat de chaîne généré par asctime_s contient exactement 26 caractères et présente la forme Wed Jan 2 02:03:55 1980\n\0. Une horloge de 24 heures est utilisée. Tous les champs ont une largeur constante. Le caractère de saut de ligne et le caractère null occupent les deux dernières positions de la chaîne. La valeur passée comme numberOfElements doit être au moins cette taille. Si ce n’est pas le cas, un code d’erreur est EINVALretourné.

_wasctime_s est une version à caractères larges de asctime_s. Sinon,_wasctime_s et asctime_s se comportent de la même façon.

Les versions de bibliothèque de débogage de ces fonctions remplissent d’abord la mémoire tampon avec 0xFE. Pour désactiver ce comportement, utilisez _CrtSetDebugFillThreshold.

Par défaut, l’état global de cette fonction est limité à l’application. Pour modifier ce comportement, consultez État global dans le CRT.

Mappage de routine de texte générique

Routine TCHAR.H _UNICODE et _MBCS non définis _MBCS défini _UNICODE défini
_tasctime_s asctime_s asctime_s _wasctime_s

En C++, l’utilisation de ces fonctions est simplifiée par les surcharges de modèle ; les surcharges peuvent déduire automatiquement la longueur de la mémoire tampon, ce qui évite d’avoir à spécifier un argument de taille. Pour plus d'informations, consultez Sécuriser les surcharges de modèle.

Spécifications

Routine En-tête requis
asctime_s <time.h>
_wasctime_s <time.h> ou <wchar.h>

Sécurité

Si le pointeur de la mémoire tampon n’est pas NULL et que le pointeur ne pointe pas vers une mémoire tampon valide, la fonction remplace tout ce qui se trouve à l’emplacement. Cette erreur peut également entraîner une violation d’accès.

Un dépassement de mémoire tampon peut se produire si l’argument de la taille passé est supérieur à la taille réelle de la mémoire tampon.

Exemple

Ce programme place l’heure système dans l’entier aclocklong, la traduit dans la structure newtime, puis la convertit en forme de chaîne pour la sortie, à l’aide de la asctime_s fonction.

// crt_asctime_s.c
#include <time.h>
#include <stdio.h>

struct tm newtime;
__time32_t aclock;

int main( void )
{
   char buffer[32];
   errno_t errNum;
   _time32( &aclock );   // Get time in seconds.
   _localtime32_s( &newtime, &aclock );   // Convert time to struct tm form.

   // Print local time as a string.

   errNum = asctime_s(buffer, 32, &newtime);
   if (errNum)
   {
       printf("Error code: %d", (int)errNum);
       return 1;
   }
   printf( "Current date and time: %s", buffer );
   return 0;
}
Current date and time: Wed May 14 15:30:17 2003

Voir aussi

Gestion des horaires
ctime_s, , _ctime32_s, _wctime_s_ctime64_s, , _wctime32_s_wctime64_s
_ftime, , _ftime32_ftime64
gmtime_s, , _gmtime32_s_gmtime64_s
localtime_s, , _localtime32_s_localtime64_s
time, , _time32_time64
_tzset