strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l

Article
06/09/2015

Copie les caractères d'une chaîne vers une autre. Des versions plus 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 and _mbsncpy_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.

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 strncpy copie les caractères initiaux count de strSource vers strDest et retourne strDest. Si count est inférieur ou égal à la longueur de strSource, un caractère NULL n'est pas ajouté automatiquement à la chaîne copiée. Si count est supérieur à la longueur de strSource, la chaîne de destination est terminée avec des caractères NULL jusqu'à la longueur count. Le comportement de strncpy est non défini si les chaînes source et de destination se superposent.

Note de sécurité
strncpy ne vérifie pas qu'il y a suffisamment d'espace dans strDest; ce qui en fait une cause potentielle des dépassements de mémoire tampon.L'argument count limite le nombre de caractères copiés ; il ne s'agit pas d'une limite sur la taille de strDest.Voir l'exemple suivant.Pour plus d'informations, consultez Solutions contre les dépassements de mémoire tampon.

Si strDest ou strSource est un pointeur NULL, ou si count est inférieure ou égale à zéro, le gestionnaire de paramètre non valide est appelé, comme décrit dans Validation de paramètre. Si l'exécution est autorisée à se poursuivre, ces fonctions retournent -1 et attribuent à errno la valeur EINVAL.

wcsncpy et _mbsncpy sont des versions à caractères élargis et à caractères multi-octets de strncpy. Les arguments et la valeur de retour de wcsncpy et de _mbsncpy varient en conséquence. Ces six fonctions se comportent sinon de façon identique.

Les versions de ces fonctions avec le suffixe _l sont identiques, sauf qu'elles utilisent les paramètres régionaux passés au lieu des paramètres régionaux actuels 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 les équivalents plus récents et sécurisés de ces fonctions. Pour plus d'informations, consultez Sécuriser les surcharges de modèle.

Mappages de routines de texte générique

Routine TCHAR.H	_UNICODE & _MBCS non définis	_MBCS défini	_UNICODE défini
_tcsncpy	strncpy	_mbsnbcpy	wcsncpy
_tcsncpy_l	_strncpy_l	_mbsnbcpy_l	_wcsncpy_l

Notes

_strncpy_l et _wcsncpy_l n'ont aucune dépendance aux paramètres régionaux, ils ne sont fournis que 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 plus d'informations sur la compatibilité de plateforme, consultez Compatibilité.

Exemple

L'exemple suivant illustre l'utilisation de strncpy et comment il peut être utilisé abusivement pour générer des bogues et des problèmes de sécurité de programme. Le compilateur génère un avertissement pour chaque appel à strncpy semblable à 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 automatique et le niveau de détection des erreurs et de protection de code peut varier avec les paramètres modifiés du compilateur. Cet exemple peut avoir des résultats différents lorsqu'il est généré dans d'autres environnements de compilation ou avec d'autres options du compilateur.