strncat_s, , _strncat_s_l, _wcsncat_s_lwcsncat_s, , _mbsncat_s_mbsncat_s_l

Ajoute des caractères à une chaîne. Ces versions de strncat, _strncat_lwcsncat_wcsncat_l, , _mbsncat, ont _mbsncat_l des améliorations de sécurité, comme décrit dans les fonctionnalités de sécurité dans le CRT.

Syntaxe

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

strDest
Chaîne de destination se terminant par un caractère Null.

numberOfElements
Taille de la mémoire tampon de destination.

strSource
Chaîne source se terminant par Null.

count
Nombre de caractères à ajouter ou _TRUNCATE.

locale
Paramètres régionaux à utiliser.

Valeur retournée

Retourne 0 si l’opération aboutit et un code d’erreur en cas d’échec.

Conditions d’erreur

Notes

Ces fonctions essaient d’ajouter les D premiers caractères de strSource à la fin de strDest, D représentant la valeur la plus petite de count et la longueur de strSource. Si l’ajout de ces D caractères s’inscrit dans strDest (dont la taille est donnée en tant que numberOfElements) et laisse toujours place à un terminateur Null, ces caractères sont ajoutés, en commençant à la valeur Null strDestd’origine, et une nouvelle valeur null de fin est ajoutée ; sinon, strDest[0] est définie sur le caractère Null et le gestionnaire de paramètres non valide est appelé, comme décrit dans la validation des paramètres.

Il existe une exception au paragraphe ci-dessus. Si count c’est _TRUNCATEle cas, la plupart des strSource éléments sont ajoutés tout strDest en laissant la place pour ajouter une valeur 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 d’ajouter trois caractères à deux caractères dans une mémoire tampon de cinq caractères longs ; il ne laisserait pas d’espace pour le terminateur Null, donc strncat_s zéros sur la chaîne et appelle le gestionnaire de paramètres non valide.

Si vous avez besoin du comportement de troncation, utilisez _TRUNCATE ou ajustez le paramètre count en conséquence :

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

or

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

Dans tous les cas, la chaîne obtenue se termine par un caractère null. Si la copie se produit entre des chaînes qui se chevauchent, le comportement est indéfini.

Si strSource ou strDest est NULLégal à zéro, numberOfElements 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 fonction retourne EINVAL sans modifier ses paramètres.

wcsncat_s et _mbsncat_s sont des versions à caractères larges et à caractères multioctets de strncat_s. Les arguments de chaîne et la valeur de retour de wcsncat_s sont des chaînes de caractères larges. Les arguments et la valeur de retour sont _mbsncat_s des chaînes de caractères multioctets. Ces trois fonctions se comportent sinon de façon identique.

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

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

Mappages de routines de texte générique

_strncat_s_l et _wcsncat_s_l ne sont pas dépendants des paramètres régionaux ; ils ne sont fournis que pour _tcsncat_s_l.

Spécifications

Pour plus d’informations sur la compatibilité, consultez Compatibility.

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();
}

Appending 4 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hi '
    new contents of dest: 'hi ther'

Appending 5 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hi '
    new contents of dest: 'hi there'

Appending 6 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hi '
    new contents of dest: 'hi there'

Destination buffer too small:

Appending 4 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hello '
Invalid parameter handler invoked: (L"Buffer is too small" && 0)
    new contents of dest: ''

Truncation examples:

Appending 'there' to 10-byte buffer dest with truncation semantics
    old contents of dest: 'hello '
    new contents of dest: 'hello the'
    truncation did occur

Appending '!' to 10-byte buffer dest with truncation semantics
    old contents of dest: 'hello '
    new contents of dest: 'hello !'
    truncation did not occur

Secure template overload example:
Invalid parameter handler invoked: (L"Buffer is too small" && 0)
    new contents of dest: ''

Voir aussi

Manipulation de chaînes
Paramètres régionaux
Interprétation des séquences de caractères multioctets
_mbsnbcat, _mbsnbcat_l
strcat, , wcscat_mbscat
strcmp, , wcscmp_mbscmp
strcpy, , wcscpy_mbscpy
strncmp, , wcsncmp_mbsncmp, ,_mbsncmp_l
strncpy, , _strncpy_l, _wcsncpy_lwcsncpy, , _mbsncpy_mbsncpy_l
_strnicmp, , _wcsnicmp, _strnicmp_l_mbsnicmp, , _wcsnicmp_l_mbsnicmp_l
strrchr, , wcsrchr_mbsrchr, ,_mbsrchr_l
_strset, , _strset_l, _wcsset_l_wcsset, , _mbsset_mbsset_l
strspn, , wcsspn_mbsspn, ,_mbsspn_l