strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l

Article
03/26/2013

Caractères de copie d'une chaîne en un autre.Ce sont des versions de strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l avec des améliorations de sécurité comme décrit dans Fonctionnalités de sécurité du CRT.

Important

_mbsncpy_s et _mbsncpy_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 strncpy_s(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count
);
errno_t _strncpy_s_l(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count,
   _locale_t locale
);
errno_t wcsncpy_s(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count 
);
errno_t _wcsncpy_s_l(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
);
errno_t _mbsncpy_s(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count 
);
errno_t _mbsncpy_s_l(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count,
   locale_t locale
);
template <size_t size>
errno_t strncpy_s(
   char (&strDest)[size],
   const char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _strncpy_s_l(
   char (&strDest)[size],
   const char *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t wcsncpy_s(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count 
); // C++ only
template <size_t size>
errno_t _wcsncpy_s_l(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t _mbsncpy_s(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count 
); // C++ only
template <size_t size>
errno_t _mbsncpy_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.
numberOfElements
La taille de la chaîne de destination, en caractères.
strSource
Chaîne source.
count
Nombre de caractères à copier, ou _TRUNCATE.
locale
Les paramètres régionaux à utiliser.

Valeur de retour

Zéro en cas de réussite, STRUNCATE si la troncation s'est produite, sinon code d'erreur.

Conditions d'erreur

strDest	numberOfElements	strSource	Valeur de retour	Contenu d' strDest
NULL	any	any	EINVAL	non modifié
any	any	NULL	EINVAL	strDest[0] a la valeur 0
any	0	any	EINVAL	non modifié
pas NULL	trop grand	any	ERANGE	strDest[0] a la valeur 0

Notes

Test de ces fonctions pour copier les premiers caractères d' D d' strSource à strDest, où D est le moins d' count et de longueur d' strSource.Si ces caractères d' D entreront 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 copiés et 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 autant d' strSource que s'insérera dans strDest est copié en quittant toujours la place pour null de fin qui est toujours ajoutée.

Par exemple :

char dst[5];

strncpy_s(dst, 5, "a long string", 5);

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

Si le comportement de troncation est requis, utilisez _TRUNCATE ou (size – 1) :

strncpy_s(dst, 5, "a long string", _TRUNCATE);

strncpy_s(dst, 5, "a long string", 4);

Notez que contrairement à strncpy, si count est supérieur à la longueur d' strSource, la chaîne de destination n'est pas rempli avec des caractères Null jusqu'à la longueur count.

Le comportement d' strncpy_s n'est pas défini si la source et les chaînes de destination se chevauchent.

Si strDest ou strSource est NULL, ou numberOfElements est 0, le gestionnaire de paramètre non valide est appelé.Si est autorisé à l'exécution pour continuer, la fonction retourne EINVAL et définit errno à EINVAL.

wcsncpy_s et _mbsncpy_s sont à caractères larges et des versions à caractères multioctets d' strncpy_s.Les arguments et la valeur de retour d' wcsncpy_s et l' mbsncpy_svarient en conséquence.Ces fonctions six 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
_tcsncpy_s	strncpy_s	_mbsnbcpy_s	wcsncpy_s
_tcsncpy_s_l	_strncpy_s_l	_mbsnbcpy_s_l	_wcsncpy_s_l

[!REMARQUE]

le _strncpy_s_l, l' _wcsncpy_s_l et l' _mbsncpy_s_l n'ont pas de dépendances de paramètres régionaux et sont fournis uniquement pour _tcsncpy_s_l et ne sont pas destinés à être appelés directement.

Configuration requise

Routine	En-tête requis
strncpy_s, _strncpy_s_l	<string.h>
wcsncpy_s, _wcsncpy_s_l	<string.h> ou <wchar.h>
_mbsncpy_s, _mbsncpy_s_l	<mbstring.h>

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

Exemple

// crt_strncpy_s_1.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 strncpy_s_tester( const char * src,
                          int count )
{
   char dest[10];

   printf( "\n" );

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

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

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

   return err;
}


void Examples()
{
   strncpy_s_tester( "howdy", 4 );
   strncpy_s_tester( "howdy", 5 );
   strncpy_s_tester( "howdy", 6 );

   printf( "\nDestination buffer too small:\n" );
   strncpy_s_tester( "Hi there!!", 10 );

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

   errno_t err = strncpy_s_tester( "How do you do?", _TRUNCATE );
   printf( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   err = strncpy_s_tester( "Howdy.", _TRUNCATE );
   printf( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

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

   char dest[10];
   strncpy( dest, "very very very long", 15 );
   // With secure template overloads enabled (see #defines at
   // top of file), the preceding line is replaced by
   //    strncpy_s( dest, _countof(dest), "very very very long", 15 );
   // Instead of causing a buffer overrun, strncpy_s invokes
   // the invalid parameter handler.
   // If secure template overloads were disabled, strncpy would
   // copy 15 characters and overrun the dest buffer.
   printf( "    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(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();
}

// crt_strncpy_s_2.c
// contrasts strncpy and strncpy_s

#include <stdio.h>
#include <stdlib.h>

int main( void )
{
   char a[20] = "test";
   char s[20];

   // simple strncpy usage:

   strcpy_s( s, 20, "dogs like cats" );
   printf( "Original string:\n   '%s'\n", s );

   // Here we can't use strncpy_s since we don't 
   // want null termination
   strncpy( s, "mice", 4 );
   printf( "After strncpy (no null-termination):\n   '%s'\n", s );
   strncpy( s+5, "love", 4 );
   printf( "After strncpy into middle of string:\n   '%s'\n", s );

   // If we use strncpy_s, the string is terminated 
   strncpy_s( s, _countof(s), "mice", 4 );
   printf( "After strncpy_s (with null-termination):\n   '%s'\n", s );

}