strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l

Article
03/26/2013

Caractères de copie d'une chaîne en un autre.Les versions sécurisées de ces fonctions sont disponibles ; consultez strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l.

Important

_mbsncpy et _mbsncpy_l ne peuvent pas être utilisés dans les applications qui s'exécutent dans Windows Runtime.Pour plus d'informations, consultez Fonctions CRT non prises en charge avec /ZW.

char *strncpy(
   char *strDest,
   const char *strSource,
   size_t count 
);
char *_strncpy_l(
   char *strDest,
   const char *strSource,
   size_t count,
   locale_t locale 
);
wchar_t *wcsncpy(
   wchar_t *strDest,
   const wchar_t *strSource,
   size_t count 
);
wchar_t *_wcsncpy_l(
   wchar_t *strDest,
   const wchar_t *strSource,
   size_t count,
   locale_t locale 
);
unsigned char *_mbsncpy(
   unsigned char *strDest,
   const unsigned char *strSource,
   size_t count 
);
unsigned char *_mbsncpy_l(
   unsigned char *strDest,
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
);
template <size_t size>
char *strncpy(
   char (&strDest)[size],
   const char *strSource,
   size_t count 
); // C++ only
template <size_t size>
char *_strncpy_l(
   char (&strDest)[size],
   const char *strSource,
   size_t count,
   locale_t locale 
); // C++ only
template <size_t size>
wchar_t *wcsncpy(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count 
); // C++ only
template <size_t size>
wchar_t *_wcsncpy_l(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count,
   locale_t locale 
); // C++ only
template <size_t size>
unsigned char *_mbsncpy(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count 
); // C++ only
template <size_t size>
unsigned char *_mbsncpy_l(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
); // C++ only

Paramètres

strDest
Chaîne de destination.
strSource
Chaîne source.
count
Nombre de caractères à copier.
locale
Paramètres régionaux à utiliser.

Valeur de retour

retourne strDest ;Aucune valeur de retour n'est réservée pour indiquer une erreur.

Notes

La fonction d' strncpy copie les caractères initiaux d' count d' strSource à strDest et retourne strDest.Si count est inférieure ou égale à la longueur d' strSource, un caractère Null n'est pas ajouté automatiquement à la chaîne copiée.Si count est supérieur à la longueur d' strSource, la chaîne de destination est remplie avec les caractères Null jusqu'à la longueur count.Le comportement d' strncpy n'est pas défini si la source et les chaînes de destination se chevauchent.

Note de sécurité
strncpy ne vérifie pas suffisamment d'espace dans strDest; cela en fait un problème potentiel les dépassements de mémoire tampon.L'argument d' count limite le nombre de caractères copiés ; ce n'est pas une limite de la taille d' strDest.Voir l'exemple suivant.Pour plus d'informations, consultez l' Solutions contre les dépassements de mémoire tampon.

Si strDest ou strSource est un pointeur d' NULL, ou si count est inférieur ou égal à zéro, le gestionnaire de paramètre non valide est appelé, comme décrit dans Validation des paramètres.Si est autorisé à l'exécution pour continuer, ces fonctions retournent -1 et affectez errno à EINVAL

wcsncpy et _mbsncpy sont à caractères larges et des versions à caractères multioctets d' strncpy.Les arguments et la valeur de retour d' wcsncpy et l' _mbsncpy varient en conséquence.Ces fonctions six se comportent de sinon.

Les versions de ces fonctions avec le suffixe d' _l sont identiques sauf qu'elles utilisent les paramètres régionaux passés au lieu des paramètres régionaux pour leur comportement dépendant des paramètres régionaux.Pour plus d'informations, consultez Paramètres régionaux.

En C++, ces fonctions ont des surcharges de modèle qui appellent le plus récent, fixent des équivalents de ces fonctions.Pour plus d'informations, consultez Surcharges sécurisées de modèle.

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	strncpy	_mbsnbcpy	wcsncpy
_tcsncpy_l	_strncpy_l	_mbsnbcpy_l	_wcsncpy_l

[!REMARQUE]

_strncpy_l et _wcsncpy_l n'ont pas de dépendances de paramètres régionaux ; ils sont fournis uniquement pour _tcsncpy_l et ne sont pas destinés à être appelés directement.

Configuration requise

Routine	En-tête requis
strncpy	<string.h>
wcsncpy	<string.h> ou <wchar.h>
_mbsncpy, _mbsncpy_l	<mbstring.h>

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

Exemple

L'exemple suivant illustre l'utilisation d' strncpy et comment il peut être abusé pour générer des bogues et des problèmes de sécurité du programme.Le compilateur génère un avertissement pour chaque appel à strncpy semblable à l' crt_strncpy_x86.c(15) : warning C4996: 'strncpy': This function or variable may be unsafe. Consider using strncpy_s instead. To disable deprecation, use _CRT_SECURE_NO_WARNINGS. See online help for details.

// crt_strncpy_x86.c
// Use this command in an x86 developer command prompt to compile: 
// cl /TC /W3 crt_strncpy_x86.c

#include <stdio.h>
#include <string.h>

int main() {
   char t[20];
   char s[20];
   char *p = 0, *q = 0;

   strcpy_s(s, sizeof(s), "AA BB CC");
   // Note: strncpy is deprecated; consider using strncpy_s instead
   strncpy(s, "aa", 2);     // "aa BB CC"         C4996
   strncpy(s + 3, "bb", 2); // "aa bb CC"         C4996
   strncpy(s, "ZZ", 3);     // "ZZ",              C4996
                            // count greater than strSource, null added
   printf("%s\n", s);

   strcpy_s(s, sizeof(s), "AA BB CC");
   p = strstr(s, "BB");
   q = strstr(s, "CC");
   strncpy(s, "aa", p - s - 1);   // "aa BB CC"   C4996
   strncpy(p, "bb", q - p - 1);   // "aa bb CC"   C4996
   strncpy(q, "cc",  q - s);      // "aa bb cc"   C4996
   strncpy(q, "dd", strlen(q));   // "aa bb dd"   C4996
   printf("%s\n", s);

   // some problems with strncpy
   strcpy_s(s, sizeof(s), "test");
   strncpy(t, "this is a very long string", 20 ); // C4996
   // Danger: at this point, t has no terminating null,
   // so the printf continues until it runs into one.
   // In this case, it will print "this is a very long test"
   printf("%s\n", t);

   strcpy_s(t, sizeof(t), "dogs like cats");
   printf("%s\n", t);

   strncpy(t + 10, "to chase cars.", 14); // C4996
   printf("%s\n", t);

   // strncpy has caused a buffer overrun and corrupted string s
   printf("Buffer overrun: s = '%s' (should be 'test')\n", s);
   // Since the stack grows from higher to lower addresses, buffer
   // overruns can corrupt function return addresses on the stack,
   // which can be exploited to run arbitrary code.
}

Sortie

La disposition des variables automatiques et du niveau de la détection d'erreurs et de la protection de code peut varier avec les paramètres modifiées de compilateur.Cet exemple peut avoir des résultats une fois généré dans d'autres environnements de compilation ou avec d'autres options du compilateur.