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.

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 d’erreur

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

Spécifications

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 rechercher d’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înes
strcat, , wcscat_mbscat, ,_mbscat_l
strcmp, , wcscmp_mbscmp, ,_mbscmp_l
strncat_s, , _strncat_s_l, _wcsncat_s_lwcsncat_s, , _mbsncat_s_mbsncat_s_l
strncmp, , wcsncmp_mbsncmp, ,_mbsncmp_l
strncpy_s, , _strncpy_s_l, _wcsncpy_s_lwcsncpy_s, , _mbsncpy_s_mbsncpy_s_l
_strnicmp, , _wcsnicmp, _strnicmp_l_mbsnicmp, , _wcsnicmp_l_mbsnicmp_l
strrchr, , wcsrchr_mbsrchr, ,_mbsrchr_l
strspn, , wcsspn_mbsspn, ,_mbsspn_l