strcpy_s, wcscpy_s, _mbscpy_s

Artículo
06/09/2015

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

Importante

_mbscpy_s no se puede 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 con /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

Parámetros

strDestination
Ubicación del búfer de cadena de destino.
numberOfElements
Tamaño del búfer de cadena de destino.
strSource
Búfer de cadena de origen terminada en NULL.

Valor devuelto

Cero si es correcto; si no, es un error.

Condiciones de error

strDestination	numberOfElements	strSource	Valor devuelto	Contenido de strDestination
NULL	any	any	EINVAL	no modificado
any	any	NULL	EINVAL	strDestination[0] se establece en 0
any	0, o demasiado pequeño	any	ERANGE	strDestination[0] se establece en 0

Comentarios

La función strcpy_s copia el contenido de la dirección de strSource, incluido el carácter null de terminación, en la ubicación especificada por strDestination. La cadena de destino debe ser lo suficientemente grande para contener la cadena de origen y el carácter null 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 carácter multibyte. Los argumentos y el valor devuelto de wcscpy_s son cadenas de caracteres anchos; los de _mbscpy_s son cadenas de caracteres multibyte. Estas tres funciones se comportan exactamente igual.

Si strDestination o strSource es un puntero null, o si la cadena de destino es demasiado pequeño, se invoca el controlador no válido de parámetro, tal y 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 strDestination o strSource es un puntero NULL y devuelven ERANGE y establecen errno en ERANGE cuando la cadena de destino es demasiado pequeña.

Sobre la ejecución correcta, la cadena de destino siempre termina en null.

En C++, el uso de estas funciones se simplifica con las sobrecargas de plantilla que pueden realizar una inferencia automáticamente de la longitud de búfer de manera que no tendrá que especificar un argumento de tamaño y pueden reemplazar automáticamente funciones anteriores no seguras con sus homólogos seguros más recientes. Para obtener más información, vea Sobrecargas de plantilla seguras.

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

Asignaciones de rutina 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

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

Para obtener información adicional de compatibilidad, vea Compatibilidad.

Ejemplo

// 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 );
}