strcpy_s, wcscpy_s, _mbscpy_s, _mbscpy_s_l

Copie une chaîne. Ces versions de , wcscpy_mbscpyont des améliorations de strcpysécurité, comme décrit dans les fonctionnalités de sécurité dans le CRT.

Important

_mbscpy_s et _mbscpy_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 dans les applications de la plateforme Windows universelle.

Syntaxe

errno_t strcpy_s(
   char *dest,
   rsize_t dest_size,
   const char *src
);
errno_t wcscpy_s(
   wchar_t *dest,
   rsize_t dest_size,
   const wchar_t *src
);
errno_t _mbscpy_s(
   unsigned char *dest,
   rsize_t dest_size,
   const unsigned char *src
);
errno_t _mbscpy_s_l(
   unsigned char *dest,
   rsize_t dest_size,
   const unsigned char *src,
   _locale_t locale
);

// Template functions are C++ only:
template <size_t size>
errno_t strcpy_s(
   char (&dest)[size],
   const char *src
); // C++ only
template <size_t size>
errno_t wcscpy_s(
   wchar_t (&dest)[size],
   const wchar_t *src
); // C++ only
template <size_t size>
errno_t _mbscpy_s(
   unsigned char (&dest)[size],
   const unsigned char *src
); // C++ only
template <size_t size>
errno_t _mbscpy_s_l(
   unsigned char (&dest)[size],
   const unsigned char *src,
   _locale_t locale
); // C++ only

Paramètres

dest
Emplacement de la mémoire tampon de chaîne de destination.

dest_size
Taille de la mémoire tampon de chaîne de destination en unités char pour les fonctions étroites et multioctets, et en unités wchar_t pour les fonctions larges. Cette valeur doit être supérieure à zéro et non supérieure à RSIZE_MAX. Vérifiez que cette taille compte pour la fin NULL suivant la chaîne.

src
Mémoire tampon de chaîne source se terminant par null.

locale
Paramètres régionaux à utiliser.

Valeur retournée

Zéro en cas de réussite ; erreur dans un autre cas.

Conditions de l’erreur

dest	dest_size	src	Valeur retournée	Contenu de dest
NULL	tous	tous	EINVAL	non modifié
tous	tous	NULL	EINVAL	dest[0] défini sur 0
tous	0 ou trop petit	tous	ERANGE	dest[0] défini sur 0

Notes

La fonction strcpy_s copie le contenu dans l'adresse de src, y compris le caractère null de fin, à l'emplacement spécifié par dest. La chaîne de destination doit être suffisamment grande pour contenir la chaîne source et son caractère null de fin. Le comportement de strcpy_s n'est pas défini si les chaînes source et de destination se chevauchent.

wcscpy_s est la version à caractères larges de strcpy_s et _mbscpy_s est la version à caractères multioctets. Les arguments de wcscpy_s ces chaînes sont des chaînes à caractères larges. Les arguments des _mbscpy_s_mbscpy_s_l chaînes de caractères multioctets et sont des arguments. Ces fonctions se comportent sinon de façon identique. _mbscpy_s_l est identique à ce _mbscpy_s qu’il utilise le paramètre de paramètres régionaux transmis au lieu des paramètres régionaux actuels. Pour plus d’informations, consultez locale.

Si dest ou src est un pointeur Null ou si la taille dest_size de chaîne de destination est trop petite, le gestionnaire de paramètres non valide est appelé, comme décrit dans la validation des paramètres. Si l'exécution est autorisée à se poursuivre, ces fonctions retournent EINVAL et attribuent à errno la valeur EINVAL quand dest ou src est un pointeur null ; elles retournent ERANGE et attribuent à errno la valeur ERANGE quand la chaîne de destination est trop petite.

Si l'exécution aboutit, la chaîne de destination se termine toujours par un caractère null.

En C++, l’utilisation de ces fonctions est simplifiée par des surcharges de modèle qui peuvent déduire automatiquement la longueur de la mémoire tampon, afin que vous n’ayez pas à spécifier d’argument de taille. Et ils peuvent remplacer automatiquement les fonctions plus anciennes et moins sécurisées par des équivalents plus récents et plus sécurisés. Pour plus d’informations, consultez Surcharges de modèles sécurisés.

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 routine de texte générique

TCHAR.H Routine	_UNICODE et _MBCS non défini	_MBCS Défini	_UNICODE Défini
_tcscpy_s	strcpy_s	_mbscpy_s	wcscpy_s

Spécifications

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

Ces fonctions sont spécifiques à Microsoft. Pour plus d’informations sur la compatibilité, consultez Compatibility.

Exemple

Contrairement au code de qualité de production, cet exemple appelle les fonctions de chaîne sécurisée sans case activée ing pour les erreurs :

// crt_strcpy_s.c
// Compile by using: cl /W4 crt_strcpy_s.c
// This program uses strcpy_s and strcat_s
// to build a phrase.

#include <string.h>     // for strcpy_s, strcat_s
#include <stdlib.h>     // for _countof
#include <stdio.h>      // for printf
#include <errno.h>      // for return values

int main(void)
{
    char stringBuffer[80];

    strcpy_s(stringBuffer, _countof(stringBuffer), "Hello world from ");
    strcat_s(stringBuffer, _countof(stringBuffer), "strcpy_s ");
    strcat_s(stringBuffer, _countof(stringBuffer), "and ");
    strcat_s(stringBuffer, _countof(stringBuffer), "strcat_s!");

    printf("stringBuffer = %s\n", stringBuffer);
}

stringBuffer = Hello world from strcpy_s and strcat_s!

Lorsque vous générez du code C++, les versions de modèle peuvent être plus faciles à utiliser.

// crt_wcscpy_s.cpp
// Compile by using: cl /EHsc /W4 crt_wcscpy_s.cpp
// This program uses wcscpy_s and wcscat_s
// to build a phrase.

#include <cstring>  // for wcscpy_s, wcscat_s
#include <cstdlib>  // for _countof
#include <iostream> // for cout, includes <cstdlib>, <cstring>
#include <errno.h>  // for return values

int main(void)
{
    wchar_t stringBuffer[80];
    // using template versions of wcscpy_s and wcscat_s:
    wcscpy_s(stringBuffer, L"Hello world from ");
    wcscat_s(stringBuffer, L"wcscpy_s ");
    wcscat_s(stringBuffer, L"and ");
    // of course we can supply the size explicitly if we want to:
    wcscat_s(stringBuffer, _countof(stringBuffer), L"wcscat_s!");

    std::wcout << L"stringBuffer = " << stringBuffer << std::endl;
}

stringBuffer = Hello world from wcscpy_s and wcscat_s!

Voir aussi

Manipulation de chaîne
strcat, wcscat, _mbscat, _mbscat_l
strcmp, wcscmp, _mbscmp, _mbscmp_l
strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l
_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l
strrchr, wcsrchr, _mbsrchr, _mbsrchr_l
strspn, wcsspn, _mbsspn, _mbsspn_l