strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l

 

Pour obtenir la dernière documentation sur Visual Studio 2017 RC, consultez Documentation Visual Studio 2017 RC.

Copie les caractères d’une chaîne à l’autre. Ces versions de strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l ont des améliorations de sécurité, comme décrit dans fonctionnalités de sécurité de la bibliothèque CRT.

System_CAPS_ICON_important.jpg Important

_mbsncpy_s et _mbsncpy_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 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
Paramètres régionaux à utiliser.

Zéro si l’opération réussit, STRUNCATE si une troncation s’est produite, sinon un code d’erreur.

Conditions d’erreur

strDestnumberOfElementsstrSourceValeur de retourContenu de strDest
NULLanyanyEINVALnon modifié
anyanyNULLEINVALstrDest[0] a la valeur 0
any0anyEINVALnon modifié
non NULLtrop petitanyERANGEstrDest[0] a la valeur 0

Ces fonctions essaient d’y copier le premier D caractères de strSource à strDest, où D est le plus petit de count et la longueur de strSource. Si ces D caractères seront inscrira strDest (dont la taille est indiquée comme numberOfElements) et toujours laisser un terminateur null, ces caractères sont copiés et un caractère null de fin est ajoutée ; sinon, strDest[0] est défini pour le caractère null et le paramètre non valide gestionnaire est appelé, comme décrit dans Validation de paramètre.

Il existe une exception au paragraphe ci-dessus. Si count est _TRUNCATE, puis autant de strSource comme s’intègre à strDest est copié tout en laissant la place pour le caractère null qui est toujours ajouté.

Par exemple :

char dst[5];

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

signifie que nous demandons strncpy_s pour copier les cinq caractères dans une mémoire tampon cinq octets de long ; ce qui laisse donc pas d’espace pour le terminateur null, strncpy_s remet la chaîne et appelle le Gestionnaire de paramètre non valide.

Si le comportement de la 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 à strncpysi count est supérieure à la longueur de strSource, la chaîne de destination n’est pas complétée avec des caractères null jusqu'à longueur count.

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

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

wcsncpy_s et _mbsncpy_s sont des versions à caractères larges et à caractères multioctets de strncpy_s. Les arguments et la valeur de retour de wcsncpy_s et mbsncpy_svarie en conséquence. Sinon, ces six fonctions se comportent à l'identique.

La valeur de sortie est affectée par la définition de la LC_CTYPE catégorie de 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 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 Secure Template Overloads.

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 et _MBCS non définis_MBCS défini_UNICODE défini
_tcsncpy_sstrncpy_s_mbsnbcpy_swcsncpy_s
_tcsncpy_s_l_strncpy_s_l_mbsnbcpy_s_l_wcsncpy_s_l
System_CAPS_ICON_note.jpg Remarque

_strncpy_s_l, _wcsncpy_s_l et _mbsncpy_s_l n’avoir aucune dépendance des paramètres régionaux et sont fournies uniquement pour _tcsncpy_s_l et n’est pas destinée à être appelée directement.

RoutineEn-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é, voir Compatibilité.

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

Copying 4 chars of 'howdy' to 10-byte buffer dest  
    new contents of dest: 'howd'  
  
Copying 5 chars of 'howdy' to 10-byte buffer dest  
    new contents of dest: 'howdy'  
  
Copying 6 chars of 'howdy' to 10-byte buffer dest  
    new contents of dest: 'howdy'  
  
Destination buffer too small:  
  
Copying 10 chars of 'Hi there!!' to 10-byte buffer dest  
Invalid parameter handler invoked: (L"Buffer is too small" && 0)  
    new contents of dest: ''  
  
Truncation examples:  
  
Copying 'How do you do?' to 10-byte buffer dest with truncation semantics  
    new contents of dest: 'How do yo'  
    truncation did occur  
  
Copying 'Howdy.' to 10-byte buffer dest with truncation semantics  
    new contents of dest: 'Howdy.'  
    truncation did not occur  
  
Secure template overload example:  
Invalid parameter handler invoked: (L"Buffer is too small" && 0)  
    new contents of dest: ''  

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

Original string:  
   'dogs like cats'  
After strncpy (no null-termination):  
   'mice like cats'  
After strncpy into middle of string:  
   'mice love cats'  
After strncpy_s (with null-termination):  
   'mice'  

System::String::Copy

Manipulation de chaînes
Paramètres régionaux
Interprétation des séquences de caractères multioctets
_mbsnbcpy, _mbsnbcpy_l
strcat_s, wcscat_s, _mbscat_s
strcmp, wcscmp, _mbscmp
strcpy_s, wcscpy_s, _mbscpy_s
strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_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

Afficher: