strcat_s, wcscat_s, _mbscat_s

Article
06/09/2015

Attache une chaîne. Ces versions strcat, wcscat, _mbscat présentent des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le CRT.

Important

_mbscat_s ne peut pas être utilisée dans les applications qui s'exécutent dans le Windows Runtime.Pour plus d'informations, consultez Fonctions CRT non prises en charge avec /ZW.

errno_t strcat_s(
   char *strDestination,
   size_t numberOfElements,
   const char *strSource 
);
errno_t wcscat_s(
   wchar_t *strDestination,
   size_t numberOfElements,
   const wchar_t *strSource 
);
errno_t _mbscat_s(
   unsigned char *strDestination,
   size_t numberOfElements,
   const unsigned char *strSource 
);
template <size_t size>
errno_t strcat_s(
   char (&strDestination)[size],
   const char *strSource 
); // C++ only
template <size_t size>
errno_t wcscat_s(
   wchar_t (&strDestination)[size],
   const wchar_t *strSource 
); // C++ only
template <size_t size>
errno_t _mbscat_s(
   unsigned char (&strDestination)[size],
   const unsigned char *strSource 
); // C++ only

Paramètres

strDestination
Mémoire tampon de chaîne source se terminant par null.
numberOfElements
Taille de la mémoire tampon de la chaîne de destination.
strSource
Mémoire tampon de chaîne source se terminant par null.

Valeur de retour

Zéro si l'opération a réussi ; code d'erreur en cas de échec.

Conditions d'erreur

strDestination	numberOfElements	strSource	Valeur de retour	Contenu de strDestination.
NULL ou incomplet	any	any	EINVAL	non modifié
any	any	NULL	EINVAL	strDestination[0] a la valeur 0
any	0, ou trop petit	any	ERANGE	strDestination[0] a la valeur 0

Notes

La fonction strcat_s ajoute strSource à strDestination et arrête la chaîne résultante avec un caractère Null. Le caractère initial de strSource remplace le caractère null de fin de strDestination. Le comportement de strcat_s est non défini si les chaînes source et de destination se superposent.

Notez que le deuxième paramètre est la taille totale de la mémoire tampon, pas la taille restante :

char buf[16];
strcpy_s(buf, 16, "Start");
strcat_s(buf, 16, " End");               // Correct
strcat_s(buf, 16 – strlen(buf), " End"); // Incorrect

wcscat_s et _mbscat_s sont des versions à caractères élargis et à caractères multi-octets de strcat_s. Les arguments et la valeur de retour de wcscat_s sont des chaînes à caractères larges ; ceux de _mbscat_s sont des chaînes de caractères multioctets. Ces trois fonctions se comportent sinon de façon identique.

Si strDestination est un pointeur null, ou ne se termine pas par null, ou si strSource est un pointeur NULL, ou si la chaîne de destination est trop petite, le gestionnaire de paramètres invalides est appelé, comme décrit dans Validation de paramètre. Si l'exécution est autorisée à se poursuivre, ces fonctions retournent EINVAL et définissent errno avec la valeur EINVAL.

En C++, l'utilisation de ces fonctions est simplifiée par les surcharges de modèle ; les surcharges peuvent déduire la longueur de la mémoire tampon automatiquement (ce qui évite d'avoir à spécifier un argument taille) et peuvent remplacer automatiquement les fonctions plus anciennes et non sécurisées par leurs équivalentes plus récentes et sécurisées. Pour plus d'informations, consultez Sécuriser les surcharges de modèle.

Les versions debug de ces fonctions remplissent d'abord la mémoire tampon avec 0xFD. Pour désactiver ce comportement, utilisez _CrtSetDebugFillThreshold.

Mappages de routines de texte générique