strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Article
03/26/2013

Ajoutez les caractères d'une chaîne.Ce sont des versions de strncat, _strncat_l, wcsncat, wcsncat_l, _mbsncat _mbsncat_l avec des améliorations de sécurité comme décrit dans Fonctionnalités de sécurité du CRT.

Important

_mbsncat_s et _mbsncat_s_l ne peuvent pas être utilisés dans les applications qui s'exécutent dans les fenêtres d'exécution.Pour plus d'informations, consultez Fonctions CRT non prises en charge avec /ZW.

errno_t strncat_s(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count
);
errno_t _strncat_s_l(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count,
   _locale_t locale
);
errno_t wcsncat_s(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count 
);
errno_t _wcsncat_s_l(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
);
errno_t _mbsncat_s(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count
);
errno_t _mbsncat_s_l(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t strncat_s(
   char (&strDest)[size],
   const char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _strncat_s_l(
   char (&strDest)[size],
   const char *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t wcsncat_s(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count 
); // C++ only
template <size_t size>
errno_t _wcsncat_s_l(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t _mbsncat_s(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbsncat_s_l(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
); // C++ only

Paramètres

[out] strDest
Chaîne de destination se terminant par null.
[in]numberOfElements
Taille de la mémoire tampon de destination.
[in]strSource
Chaîne se terminant par null source.
[in]count
Nombre de caractères à ajouter, ou _TRUNCATE.
[in] locale
Paramètres régionaux à utiliser.

Valeur de retour

Retourne 0 si l'opération a réussi, le code d'erreur en cas de échec.

Conditions d'erreur

strDestination	numberOfElements	strSource	Valeur de retour	Contenu d' strDestination
NULL ou unterminated	any	any	EINVAL	non modifié
any	any	NULL	EINVAL	non modifié
any	0, ou trop grand	any	ERANGE	non modifié

Notes

Test de ces fonctions pour ajouter les premiers caractères d' D d' strSource à la fin de strDest, où D est le moins d' count et de longueur d' strSource.Si ajouter ces caractères d' D entrera dans strDest (dont la taille est spécifiée comme numberOfElements) et quitter toujours la place pour une marque de fin null, ensuite ces caractères sont ajoutés, en commençant à null de fin d'origine d' strDest, puis nouveau null de fin est ajouté ; sinon, strDest[0] a pour valeur le caractère NULL et au gestionnaire de paramètre non valide est appelé, comme décrit dans Validation des paramètres.

Il existe une exception au paragraphe ci-dessus.Si count est _TRUNCATE puis aussi bien d' strSource que s'adaptera est ajouté à strDest en quittant toujours la partie d'ajouter null de fin.

Par exemple :

char dst[5];

strncpy_s(dst, _countof(dst), "12", 2);

strncat_s(dst, _countof(dst), "34567", 3);

signifie que nous demandons à strncat_s pour ajouter trois caractères à deux caractères caractères d'une mémoire tampon cinq long ; cela ne laisserait aucun espace pour la marque de fin null par conséquent, les zéros de strncat_s la chaîne et appelle le gestionnaire de paramètre non valide.

Si le comportement de troncation est requis, utilisez _TRUNCATE ou ajuster le paramètre d' size en conséquence :

strncat_s(dst, _countof(dst), "34567", _TRUNCATE);

strncat_s(dst, _countof(dst), "34567", _countof(dst)-strlen(dst)-1);

Dans tous les cas, la chaîne résultante est terminée avec un caractère Null.Si copier nécessaire entre les chaînes qui se chevauchent, le comportement est pas défini.

Si strSource ou strDest est NULL, ou est numberOfElements est zéro, le gestionnaire de paramètre non valide est appelé, comme décrit dans Validation des paramètres .Si est autorisé à l'exécution pour continuer, la fonction retourne EINVAL sans modifier ses paramètres.

wcsncat_s et _mbsncat_s sont à caractères larges et des versions à caractères multioctets d' strncat_s.Les arguments de chaîne et la valeur de retour d' wcsncat_s sont des chaînes à caractères larges ; ces d' _mbsncat_s sont des chaînes de caractères multioctets.Ces trois fonctions se comportent de sinon.

La valeur de sortie est affectée par la configuration de la définition de catégorie d' LC_CTYPE des paramètres régionaux ; consultez l' setlocale pour plus d'informations.Les versions de ces fonctions sans suffixe d' _l utilisent les paramètres régionaux définis pour ce comportement dépendant des paramètres régionaux ; les versions avec le suffixe d' _l sont identiques sauf qu'elles utilisent le paramètre de paramètres régionaux passé à la place.Pour plus d'informations, consultez Paramètres régionaux.

En C++, l'utilisation de ces fonctions est simplifié par des surcharges de modèle ; les surcharges peuvent également déduire la longueur de la mémoire tampon automatiquement (éliminant le besoin de spécifier un argument de taille) et peuvent remplacer automatiquement des fonctions plus anciennes et non sécurisées par leurs nouvelles, sécurisées équivalents.Pour plus d'informations, consultez Surcharges sécurisées de modèle.

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

Mappages de routines de texte générique

Routine de TCHAR.H	_UNICODE et non définis _MBCS	_MBCS défini	_UNICODE défini
_tcsncat_s	strncat_s	_mbsnbcat_s	wcsncat_s
_tcsncat_s_l	_strncat_s_l	_mbsnbcat_s_l	_wcsncat_s_l

_strncat_s_l et _wcsncat_s_l n'ont pas de dépendances de paramètres régionaux ; ils sont fournis uniquement pour _tcsncat_s_l.

Configuration requise

Routine	En-tête requis
strncat_s	<string.h>
wcsncat_s	<string.h> ou <wchar.h>
_mbsncat_s, _mbsncat_s_l	<mbstring.h>

Pour des informations de compatibilité supplémentaires, consultez l' Compatibilité dans l'introduction.

Exemple

// crt_strncat_s.cpp
// compile with: /MTd

// These #defines enable secure template overloads
// (see last part of Examples() below)
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1 
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT 1

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <crtdbg.h>  // For _CrtSetReportMode
#include <errno.h>

// This example uses a 10-byte destination buffer.

errno_t strncat_s_tester( const char * initialDest,
                          const char * src,
                          int count )
{
   char dest[10];
   strcpy_s( dest, _countof(dest), initialDest );

   printf_s( "\n" );

   if ( count == _TRUNCATE )
      printf_s( "Appending '%s' to %d-byte buffer dest with truncation semantics\n",
               src, _countof(dest) );
   else
      printf_s( "Appending %d chars of '%s' to %d-byte buffer dest\n",
              count, src, _countof(dest) );

   printf_s( "    old contents of dest: '%s'\n", dest );

   errno_t err = strncat_s( dest, _countof(dest), src, count );

   printf_s( "    new contents of dest: '%s'\n", dest );

   return err;
}


void Examples()
{
   strncat_s_tester( "hi ", "there", 4 );
   strncat_s_tester( "hi ", "there", 5 );
   strncat_s_tester( "hi ", "there", 6 );

   printf_s( "\nDestination buffer too small:\n" );
   strncat_s_tester( "hello ", "there", 4 );

   printf_s( "\nTruncation examples:\n" );

   errno_t err = strncat_s_tester( "hello ", "there", _TRUNCATE );
   printf_s( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   err = strncat_s_tester( "hello ", "!", _TRUNCATE );
   printf_s( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   printf_s( "\nSecure template overload example:\n" );

   char dest[10] = "cats and ";
   strncat( dest, "dachshunds", 15 );
   // With secure template overloads enabled (see #define
   // at top of file), the preceding line is replaced by
   //    strncat_s( dest, _countof(dest), "dachshunds", 15 );
   // Instead of causing a buffer overrun, strncat_s invokes
   // the invalid parameter handler.
   // If secure template overloads were disabled, strncat would
   // append "dachshunds" and overrun the dest buffer.
   printf_s( "    new contents of dest: '%s'\n", dest );
}

void myInvalidParameterHandler(
   const wchar_t* expression,
   const wchar_t* function, 
   const wchar_t* file, 
   unsigned int line, 
   uintptr_t pReserved)
{
   wprintf_s(L"Invalid parameter handler invoked: %s\n", expression);
}

int main( void )
{
   _invalid_parameter_handler oldHandler, newHandler;

   newHandler = myInvalidParameterHandler;
   oldHandler = _set_invalid_parameter_handler(newHandler);
   // Disable the message box for assertions.
   _CrtSetReportMode(_CRT_ASSERT, 0);

   Examples();
}