strcpy_s, wcscpy_s, _mbscpy_s, _mbscpy_s_l

Copia una cadena. Estas versiones de strcpy, wcscpytienen _mbscpy mejoras de seguridad, como se describe en Características de seguridad de CRT.

Importante

_mbscpy_s y _mbscpy_s_l no se pueden usar en aplicaciones que se ejecutan en Windows en tiempo de ejecución. Para obtener más información, vea Funciones de CRT no admitidas en aplicaciones de la Plataforma universal de Windows.

Sintaxis

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

Parámetros

dest
Ubicación del búfer de cadena de destino.

dest_size
Tamaño del búfer de cadena de destino en unidades char para las funciones estrechas y multibyte, y unidades wchar_t para las funciones anchas. Este valor debe ser mayor que cero y no mayor que RSIZE_MAX. Asegúrese de que este tamaño tenga en cuenta la terminación NULL después de la cadena.

src
Búfer de cadena de origen terminada en NULL.

locale
Configuración regional que se va a usar.

Valor devuelto

Cero si es correcto; en caso contrario, error.

Condiciones de error

dest	dest_size	src	Valor devuelto	Contenido de dest
NULL	cualquiera	cualquiera	EINVAL	no modificado
cualquiera	cualquiera	NULL	EINVAL	dest[0] configurado en 0
cualquiera	0, o demasiado pequeño	cualquiera	ERANGE	dest[0] configurado en 0

Comentarios

La función strcpy_s copia el contenido de la dirección de src, incluido el carácter nulo de terminación, en la ubicación especificada por dest. La cadena de destino debe ser lo suficientemente grande como para contener la cadena de origen y su carácter nulo de terminación. El comportamiento de strcpy_s no se define si las cadenas de origen y de destino se superponen.

wcscpy_s es la versión con caracteres anchos de strcpy_s y _mbscpy_s es la versión de caracteres multibyte. Los argumentos de son cadenas de wcscpy_s caracteres anchos. Los argumentos de y _mbscpy_s_l son cadenas de _mbscpy_s caracteres multibyte. Por lo demás, estas funciones se comportan exactamente igual. _mbscpy_s_l es exactamente igual que _mbscpy_s, salvo que usa el parámetro de configuración regional que se pasa. Para obtener más información, vea locale.

Si dest o src es un puntero nulo, o si el tamaño dest_size de la cadena de destino es demasiado pequeño, se invoca el controlador de parámetros no válidos, como se describe en Validación de parámetros. Si la ejecución puede continuar, estas funciones devuelven EINVAL y establecen errno en EINVAL cuando dest o src es un puntero nulo, y devuelven ERANGE y establecen errno en ERANGE cuando la cadena de destino es demasiado pequeña.

Si la ejecución finaliza correctamente, la cadena de destino siempre termina en null.

En C++, el uso de estas funciones se simplifica mediante sobrecargas de plantilla que pueden deducir la longitud del búfer automáticamente, de modo que no tenga que especificar un argumento de tamaño. Además, pueden reemplazar automáticamente las funciones más antiguas y menos seguras con homólogos más recientes y seguros. Para obtener más información, consulte Sobrecargas de plantillas seguras.

Las versiones de la biblioteca de depuración de estas funciones rellenan primero el búfer con 0xFE. Para deshabilitar este comportamiento, use _CrtSetDebugFillThreshold.

De manera predeterminada, el estado global de esta función está limitado a la aplicación. Para cambiar este comportamiento, consulte Estado global en CRT.

Asignaciones de rutinas de texto genérico

Rutina TCHAR.H	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_tcscpy_s	strcpy_s	_mbscpy_s	wcscpy_s

Requisitos

Routine	Encabezado necesario
strcpy_s	<string.h>
wcscpy_s	<string.h> o <wchar.h>
_mbscpy_s	<mbstring.h>

Estas funciones son específicas de Microsoft. Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Ejemplo

A diferencia del código con calidad de producción, este ejemplo llama a las funciones de cadena seguras sin comprobar si hay errores:

// 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!

Al compilar código de C++, es posible que las versiones de plantilla sean más fáciles de usar.

// 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!

Consulte también

Manipulación de cadenas
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