strcpy_s, wcscpy_s, _mbscpy_s

Article
06/09/2015

Copie une chaîne. Ces versions strcpy, wcscpy, _mbscpy présentent des améliorations de sécurité, comme décrit dans Fonctionnalités de sécurité dans le CRT.

Important

_mbscpy_s ne peut pas être utilisé 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 strcpy_s(
   char *strDestination,
   size_t numberOfElements,
   const char *strSource 
);
errno_t wcscpy_s(
   wchar_t *strDestination,
   size_t numberOfElements,
   const wchar_t *strSource 
);
errno_t _mbscpy_s(
   unsigned char *strDestination,
   size_t numberOfElements,
   const unsigned char *strSource 
);
template <size_t size>
errno_t strcpy_s(
   char (&strDestination)[size],
   const char *strSource 
); // C++ only
template <size_t size>
errno_t wcscpy_s(
   wchar_t (&strDestination)[size],
   const wchar_t *strSource 
); // C++ only
template <size_t size>
errno_t _mbscpy_s(
   unsigned char (&strDestination)[size],
   const unsigned char *strSource 
); // C++ only

Paramètres

strDestination
Emplacement de la mémoire tampon de la chaîne de destination.
numberOfElements
Taille de la mémoire tampon de la chaîne de destination.
strSource
Mémoire tampon de chaîne source se terminant par null.

Valeur de retour

Zéro correspond à une opération réussie. Sinon, il s'agit d'une erreur.

Conditions d'erreur

strDestination	numberOfElements	strSource	Valeur de retour	Contenu de strDestination.
NULL	any	any	EINVAL	non modifié
any	any	NULL	EINVAL	strDestination[0] a la valeur 0
any	0, ou trop petit	any	ERANGE	strDestination[0] a la valeur 0

Notes

La fonction strcpy_s copie le contenu de l'adresse de strSource, y compris le caractère null de fin, sur l'emplacement spécifié par strDestination. La chaîne de destination doit être assez grande pour contenir la chaîne source et son caractère null de fin. Le comportement de strcpy_s est non défini si les chaînes source et de destination se superposent.

wcscpy_s est la version à caractères larges de strcpy_s et _mbscpy_s la version à caractères multioctets. Les arguments et la valeur de retour de wcscpy_s sont des chaînes à caractères larges ; ceux de _mbscpy_s sont des chaînes de caractères multioctets. Ces trois fonctions se comportent sinon de façon identique.

Si strDestination ou strSource est un pointeur null ou que la chaîne de destination est trop petite, le gestionnaire de paramètres non valides est appelé, comme décrit dans Validation de paramètre. Si l'exécution peut continuer, ces fonctions retournent EINVAL et définissent errno sur EINVAL lorsque strDestination ou strSource est un pointeur null, et retournent ERANGE et définissent errno sur ERANGE lorsque la chaîne de destination est trop petite.

Une fois l'exécution réussie, la chaîne de destination se termine toujours par null.

En C++, l'utilisation de ces fonctions est simplifiée par les surcharges de modèle qui 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 moins sécurisées par leurs équivalents plus récents et mieux sécurisés. 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 0xFE. 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
_tcscpy_s	strcpy_s	_mbscpy_s	wcscpy_s

Configuration requise

Routine	En-tête requis
strcpy_s	<string.h>
wcscpy_s	<string.h> ou <wchar.h>
_mbscpy_s	<mbstring.h>

Pour plus d'informations sur la compatibilité, consultez Compatibilité.

Exemple

// crt_strcpy_s.cpp
// This program uses strcpy_s and strcat_s
// to build a phrase.
//

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

int main( void )
{
   char string[80];
   // using template versions of strcpy_s and strcat_s:
   strcpy_s( string, "Hello world from " );
   strcat_s( string, "strcpy_s " );
   strcat_s( string, "and " );
   // of course we can supply the size explicitly if we want to:
   strcat_s( string, _countof(string), "strcat_s!" );
   
   printf( "String = %s\n", string );
}