strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l

Article
06/09/2015

Copie les caractères d'une chaîne vers une autre. Ces versions strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l présentent des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le CRT.

Important

_mbsncpy_s et _mbsncpy_s_l ne peuvent pas être utilisés 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 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,en nombre de caractères,de la chaîne destinataire.
strSource
Chaîne source.
count
Le nombre de caractères à copier, ou _TRUNCATE.
locale
Paramètres régionaux à utiliser.

Valeur de retour

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

Conditions d'erreur

strDest	numberOfElements	strSource	Valeur de retour	Contenu de 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 petit	any	ERANGE	strDest[0] a la valeur 0

Notes

Ces fonctions tentent de copier les premiers caractères D de strSource vers strDest, où D est le plus petit de count et la longueur de strSource. Si ces caractères D rentrent dans strDest (dont la taille est définie à la valeur numberOfElements) et ont toujours de la place pour un terminateur null, alors ces caractères y sont copiés et un terminateur null est ajouté en queue ; sinon, strDest[0] est réglé au caractère null et le programme de traitement des paramètres invalides est appelé, ainsi qu'il est décrit dans Validation de paramètre.

Il existe une exception au paragraphe ci-dessus. Si count est _TRUNCATE, alors tous les éléments de strSource qui rentrent dans strDest y sont copiés tout en laissant suffusamment de place pour null qui est toujours ajoutée en queue.

Par exemple :

char dst[5];

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

signifie que nous demandons à strncpy_s de copier cinq caractères dans une mémoire tampon de cinq octets de long ; cela ne laisserait aucun espace pour le terminateur null, par conséquent strncpy_s remplit la chaîne de zéros et appelle le programme de traitement des paramètres non valide.

Si le comportement de troncation est nécessaire, 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 de strSource, la chaîne de destination n'est pas rempli avec des caractères null sur toute la longueur count.

Le comportement de strncpy_s est non défini si les chaînes source et de destination se superposent.

Si strDest ou strSource est NULL, ou si la valeur de numberOfElements est 0, le programme de traitement des paramètres non valide est appelé. Si l'exécution est autorisée à se poursuivre, la fonction retourne EINVAL et définit errno à la valeur EINVAL.

wcsncpy_s et _mbsncpy_s sont des versions à caractères élargis et à caractères multi-octets de strncpy_s. Les arguments et la valeur de retour de wcsncpy_s et de mbsncpy_svarient en conséquence. Ces six 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 ; consultez setlocale, pour plus d'informations. Les versions de ces fonctions sans le suffixe _l utilisent les paramètres régionaux pour ce comportement dépendant des paramètres régionaux ; les versions avec le suffixe _l sont identiques, sauf qu'elles utilisent à la place les paramètres régionaux transmis. Pour plus d'informations, consultez Paramètres régionaux.

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

Routine TCHAR.H	_UNICODE & _MBCS non définis	_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

Notes

_strncpy_s_l, l' _wcsncpy_s_l et _mbsncpy_s_l n'ont aucune dépendance aux paramètres régionaux, ne sont fournis que 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 plus d'informations sur la compatibilité, consultez Compatibilité.

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

}