`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`

Article
10/12/2023

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.

Important

_mbsncat_s et _mbsncat_s_l ne peuvent pas être utilisées dans les applications qui s'exécutent dans Windows Runtime. Pour plus d’informations, consultez Fonctions CRT non prises en charge dans les applications de la plateforme Windows universelle.

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 de l’erreur

`strDestination`	`numberOfElements`	`strSource`	Valeur retournée	Contenu de `strDestination`
`NULL` ou inachevé	tous	tous	`EINVAL`	non modifié
tous	tous	`NULL`	`EINVAL`	non modifié
tous	0 ou trop petit	tous	`ERANGE`	non modifié

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

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 sont wcsncat_s des chaînes à 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 sortie est affectée par le paramètre de 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 Surcharges de modèles sécurisés.

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 routine de texte générique

Routine TCHAR.H	`_UNICODE` et `_MBCS` non défini	`_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 ne sont pas dépendants des paramètres régionaux ; ils ne sont fournis que pour _tcsncat_s_l.

Spécifications

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

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îne
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, _wcsncpy_l, _mbsncpy, _mbsncpy_l
_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l
strrchr, wcsrchr, _mbsrchr, _mbsrchr_l
_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l
strspn, wcsspn, _mbsspn, _mbsspn_l

Share via

`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`

Syntaxe

Paramètres

Valeur retournée

Conditions de l’erreur

Notes

Mappages de routine de texte générique

Spécifications

Exemple

Voir aussi

Commentaires

Commentaires

Ressources supplémentaires

Share via

strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Syntaxe

Paramètres

Valeur retournée

Conditions de l’erreur

Notes

Mappages de routine de texte générique

Spécifications

Exemple

Voir aussi

Commentaires

Commentaires

Ressources supplémentaires

`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`