strcat_s, wcscat_s, _mbscat_s, _mbscat_s_l

Anexa una cadena. Estas versiones de strcat, wcscattienen _mbscat mejoras de seguridad, como se describe en Características de seguridad de CRT.

Importante

_mbscat_s y _mbscat_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 strcat_s(
   char *strDestination,
   size_t numberOfElements,
   const char *strSource
);
errno_t wcscat_s(
   wchar_t *strDestination,
   size_t numberOfElements,
   const wchar_t *strSource
);
errno_t _mbscat_s(
   unsigned char *strDestination,
   size_t numberOfElements,
   const unsigned char *strSource
);
errno_t _mbscat_s_l(
   unsigned char *strDestination,
   size_t numberOfElements,
   const unsigned char *strSource,
   _locale_t locale
);
template <size_t size>
errno_t strcat_s(
   char (&strDestination)[size],
   const char *strSource
); // C++ only
template <size_t size>
errno_t wcscat_s(
   wchar_t (&strDestination)[size],
   const wchar_t *strSource
); // C++ only
template <size_t size>
errno_t _mbscat_s(
   unsigned char (&strDestination)[size],
   const unsigned char *strSource
); // C++ only
template <size_t size>
errno_t _mbscat_s_l(
   unsigned char (&strDestination)[size],
   const unsigned char *strSource,
   _locale_t locale
); // C++ only

Parámetros

strDestination
Búfer de cadena de destino terminada en NULL.

numberOfElements
Tamaño del búfer de cadena de destino.

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

locale
Configuración regional que se va a usar.

Valor devuelto

Devuelve cero si se ejecuta correctamente; devuelve un código de error si se produce un error.

Condiciones de error

strDestination	numberOfElements	strSource	Valor devuelto	Contenido de strDestination
NULL o sin terminar	cualquiera	cualquiera	EINVAL	no modificado
cualquiera	cualquiera	NULL	EINVAL	strDestination[0] configurado en 0
cualquiera	0, o demasiado pequeño	cualquiera	ERANGE	strDestination[0] configurado en 0

Comentarios

La función strcat_s anexa strSource a strDestination y termina la cadena resultante con un carácter nulo. El carácter inicial de strSource sobrescribe el carácter nulo de terminación de strDestination. El comportamiento de strcat_s no se define si las cadenas de origen y de destino se superponen.

El segundo parámetro es el tamaño total del búfer, no el tamaño restante:

char buf[16];
strcpy_s(buf, 16, "Start");
strcat_s(buf, 16, " End");               // Correct
strcat_s(buf, 16 - strlen(buf), " End"); // Incorrect

wcscat_s y _mbscat_s son versiones de caracteres anchos y multibyte de strcat_s. Los argumentos y el valor devuelto de son cadenas de wcscat_s caracteres anchos. Los argumentos y el valor devuelto de son cadenas de _mbscat_s caracteres multibyte. Estas tres funciones se comportan exactamente igual.

Si strDestination es un puntero nulo o no está terminado en NULL, o si es un NULL puntero, o si strSource la cadena de destino es demasiado pequeña, 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.

Las versiones de estas funciones que tienen el sufijo _l tienen el mismo comportamiento, pero usan el parámetro de configuración regional que se pasa en lugar de la configuración regional actual. Para obtener más información, vea Locale.

En C++, el uso de estas funciones se simplifica con las sobrecargas de plantilla; las sobrecargas pueden realizar una inferencia automáticamente de la longitud de búfer (lo que elimina el requisito de 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, 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
_tcscat_s	strcat_s	_mbscat_s	wcscat_s

Requisitos

Routine	Encabezado necesario
strcat_s	<string.h>
wcscat_s	<string.h> o <wchar.h>
_mbscat_s	<mbstring.h>

Para obtener más información sobre compatibilidad, consulte Compatibilidad.

Ejemplo

Vea el ejemplo de código de strcpy_s, wcscpy_s, _mbscpy_s.

Consulte también

Manipulación de cadenas
strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l
strncmp, wcsncmp, _mbsncmp, _mbsncmp_l
strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l
_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l
strrchr, wcsrchr, _mbsrchr, _mbsrchr_l
strspn, wcsspn, _mbsspn, _mbsspn_l