strncpy_s, , _strncpy_s_l, _wcsncpy_s_lwcsncpy_s, , _mbsncpy_s_l_tcsnccpy_s_tcsncpy_s_tcsncpy_s_l_mbsncpy_s_tcsnccpy_s_l

Copie les caractères d’une chaîne dans une autre. Ces versions de strncpy, _strncpy_lwcsncpy_wcsncpy_l, , _mbsncpy, ont _mbsncpy_l des améliorations de sécurité, comme décrit dans les fonctionnalités de sécurité dans le CRT.

Pour _tcsnccpy_s, _tcsnccpy_s_l, _tcsnccpy_set _tcsnccpy_s_l consultez les mappages de fonctions de texte générique.

Syntaxe

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

Valeur retournée

Zéro si l’opération réussit, STRUNCATE si une troncation s’est produite, code d’erreur dans tout autre cas.

Conditions d’erreur

Notes

Ces fonctions essaient de copier les D premiers caractères de strSource dans strDest, D représentant la valeur la plus petite de count et la longueur de strSource. Si ces D caractères s’intègrent ( strDest dont la taille est donnée en tant que numberOfElements) et conservent la place pour un terminateur Null, ces caractères sont copiés et une valeur null de fin est ajoutée ; sinon, strDest[0] elle 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 strDest copiés tout en laissant place à la valeur null de fin, qui est toujours ajoutée.

Par exemple,

char dst[5];
strncpy_s(dst, 5, "a long string", 5);

signifie qu’il strncpy_s copie cinq caractères dans une mémoire tampon de 5 octets. Cette copie ne laisserait pas d’espace pour le terminateur Null, donc strncpy_s zéros sur la chaîne et appelle le gestionnaire de 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);

Contrairement strncpyà , si count elle est supérieure à la longueur de , la chaîne de strSourcedestination n’est pas remplie avec des caractères Null jusqu’à la 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 a la valeur NULL, ou si numberOfElements a la valeur 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 varient wcsncpy_s mbsncpy_s en conséquence. Sinon, ces six fonctions se comportent à l'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 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 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 fonctions de texte générique

La fonction dans la tchar.h colonne est mappée à la fonction dans les autres colonnes en fonction du jeu de caractères défini au moment de la compilation.

Spécifications

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

Exemple : Copier des caractères dans une mémoire tampon

// 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: ''

Exemple : strncpy et strncpy_s

// 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'

Voir aussi

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_lwcsncat_s, , _mbsncat_s_mbsncat_s_l
strncmp, , wcsncmp_mbsncmp, ,_mbsncmp_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