strcpy_s, wcscpy_s, _mbscpy_s

Artículo
04/10/2013

Copie una cadena.Éstas son versiones de strcpy, wcscpy, _mbscpy con mejoras de seguridad como se describe en Características de seguridad en CRT.

Importante
_mbscpy_s no se puede utilizar en las aplicaciones que se ejecutan en tiempo de ejecución de Windows.Para obtener más información, vea Funciones CRT no compatibles 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 terminada en null de origen.

Valor devuelto

Cero si correctamente; un error de otra manera.

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, demasiado pequeño	any	ERANGE	strDestination[0] se establece en 0

Comentarios

La función de 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, incluyendo el carácter null de terminación.El comportamiento de strcpy_s es indefinido si las cadenas de origen y de destino se superponen.

wcscpy_s y _mbscpy_s son versiones de caracteres anchos y de multibyte- carácter de strcpy_s respectivamente.Los argumentos y el valor devuelto de wcscpy_s son cadenas de caracteres anchos; las de _mbscpy_s son cadenas de caracteres multibyte.Estas tres funciones se comportan exactamente igual de otra manera.

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 del parámetro tal como se describe en Validación de parámetros.Si la ejecución puede continuar, estas funciones EINVAL return y errno determinado a EINVAL.

Sobre la ejecución correcta, la cadena de destino siempre será null cancelada.

En C++, mediante estas funciones es simplificado con sobrecargas de plantilla; las sobrecargas pueden deducir la longitud de búfer automáticamente (que elimina la necesidad de especificar un argumento de tamaño) y automáticamente pueden reemplazar anterior, funciones de no Secure con sus más recientes, seguros homólogos.Para obtener más información, vea Sobrecargas de plantilla de seguridad.

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

Asignaciones de la rutina de Genérico- texto

Rutina de 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 en la Introducción.

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