strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Artículo
06/09/2015

Anexa caracteres a una cadena. Estas versiones de strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l tienen mejoras de seguridad, como se describe en Características de seguridad de CRT.

Importante

_mbsncat_s y _mbsncat_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 con /ZW.

errno_t strncat_s(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count
);
errno_t _strncat_s_l(
   char *strDest,
   size_t numberOfElements,
   const char *strSource,
   size_t count,
   _locale_t locale
);
errno_t wcsncat_s(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count 
);
errno_t _wcsncat_s_l(
   wchar_t *strDest,
   size_t numberOfElements,
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
);
errno_t _mbsncat_s(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count
);
errno_t _mbsncat_s_l(
   unsigned char *strDest,
   size_t numberOfElements,
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
);
template <size_t size>
errno_t strncat_s(
   char (&strDest)[size],
   const char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _strncat_s_l(
   char (&strDest)[size],
   const char *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t wcsncat_s(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count 
); // C++ only
template <size_t size>
errno_t _wcsncat_s_l(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count,
   _locale_t locale
); // C++ only
template <size_t size>
errno_t _mbsncat_s(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count
); // C++ only
template <size_t size>
errno_t _mbsncat_s_l(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
); // C++ only

Parámetros

[out] strDest
Cadena de destino terminada en NULL.
[in]numberOfElements
Tamaño del búfer de destino.
[in]strSource
Cadena de origen terminada en NULL.
[in]count
Número de caracteres que se van a anexar, o _TRUNCATE.
[in] locale
Configuración regional que se va a usar.

Valor devuelto

Devuelve 0 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	any	any	EINVAL	no modificado
any	any	NULL	EINVAL	no modificado
any	0, o demasiado pequeño	any	ERANGE	no modificado

Comentarios

Estas funciones intentan anexar los primeros caracteres D de strSource al final de strDest, donde D es el valor menor de count o la longitud de strSource. Si los caracteres D que se van a anexar caben en strDest (cuyo tamaño se da como numberOfElements) y todavía queda espacio para un terminador nulo, entonces se anexan, empezando a partir del terminador nulo original de strDest, y se anexa un nuevo terminador nulo; de lo contrario, strDest[0] se establece en el carácter nulo y se invoca el controlador de parámetros no válidos, como se describe en Validación de parámetros.

Existe una excepción al comportamiento anterior. Si count es _TRUNCATE, la parte de strSource que quepa se anexa a strDest, siempre dejando espacio para anexar un carácter final nulo.

Por ejemplo,

char dst[5];

strncpy_s(dst, _countof(dst), "12", 2);

strncat_s(dst, _countof(dst), "34567", 3);

significa que se solicita a strncat_s que anexe tres caracteres a dos caracteres en un búfer de cinco caracteres; así no quedaría espacio para el terminador nulo, por lo que strncat_s pone a cero la cadena y llama al controlador de parámetros no válidos.

Si es necesario el comportamiento de truncamiento, use _TRUNCATE o ajuste el parámetro size como corresponda:

strncat_s(dst, _countof(dst), "34567", _TRUNCATE);

-O bien-

strncat_s(dst, _countof(dst), "34567", _countof(dst)-strlen(dst)-1);

En todos los casos, la cadena resultante se termina con un carácter nulo. Si la copia tiene lugar entre cadenas que se superponen, el comportamiento es indefinido.

Si strSource o strDest es NULL, o si numberOfElements es cero, 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, la función devuelve EINVAL sin modificar sus parámetros.

wcsncat_s y _mbsncat_s son versiones de caracteres anchos y multibyte de strncat_s. Los argumentos de cadena y el valor devuelto de wcsncat_s son cadenas de caracteres anchos; los de _mbsncat_s son cadenas de caracteres multibyte. Estas tres funciones se comportan exactamente igual.

El valor de salida se ve afectado por el valor de la categoría LC_CTYPE de la configuración regional; vea setlocale para obtener más información. Las versiones de estas funciones sin el sufijo _l usan la configuración regional actual de su comportamiento dependiente de la configuración regional; las versiones con el sufijo _l son idénticas salvo que usan el parámetro locale pasado en su lugar. Para obtener más información, vea Configuración regional.

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 la necesidad 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, vea Sobrecargas de plantilla seguras.

Las versiones de depuración de estas funciones rellenan primero el búfer con 0xFD. 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
_tcsncat_s	strncat_s	_mbsnbcat_s	wcsncat_s
_tcsncat_s_l	_strncat_s_l	_mbsnbcat_s_l	_wcsncat_s_l

_strncat_s_l y _wcsncat_s_l no dependen de la configuración regional; se proporcionan solo para _tcsncat_s_l.

Requisitos

Rutina	Encabezado necesario
strncat_s	<string.h>
wcsncat_s	<string.h> o <wchar.h>
_mbsncat_s, _mbsncat_s_l	<mbstring.h>

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

Ejemplo

// crt_strncat_s.cpp
// compile with: /MTd

// These #defines enable secure template overloads
// (see last part of Examples() below)
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1 
#define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT 1

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <crtdbg.h>  // For _CrtSetReportMode
#include <errno.h>

// This example uses a 10-byte destination buffer.

errno_t strncat_s_tester( const char * initialDest,
                          const char * src,
                          int count )
{
   char dest[10];
   strcpy_s( dest, _countof(dest), initialDest );

   printf_s( "\n" );

   if ( count == _TRUNCATE )
      printf_s( "Appending '%s' to %d-byte buffer dest with truncation semantics\n",
               src, _countof(dest) );
   else
      printf_s( "Appending %d chars of '%s' to %d-byte buffer dest\n",
              count, src, _countof(dest) );

   printf_s( "    old contents of dest: '%s'\n", dest );

   errno_t err = strncat_s( dest, _countof(dest), src, count );

   printf_s( "    new contents of dest: '%s'\n", dest );

   return err;
}


void Examples()
{
   strncat_s_tester( "hi ", "there", 4 );
   strncat_s_tester( "hi ", "there", 5 );
   strncat_s_tester( "hi ", "there", 6 );

   printf_s( "\nDestination buffer too small:\n" );
   strncat_s_tester( "hello ", "there", 4 );

   printf_s( "\nTruncation examples:\n" );

   errno_t err = strncat_s_tester( "hello ", "there", _TRUNCATE );
   printf_s( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   err = strncat_s_tester( "hello ", "!", _TRUNCATE );
   printf_s( "    truncation %s occur\n", err == STRUNCATE ? "did"
                                                       : "did not" );

   printf_s( "\nSecure template overload example:\n" );

   char dest[10] = "cats and ";
   strncat( dest, "dachshunds", 15 );
   // With secure template overloads enabled (see #define
   // at top of file), the preceding line is replaced by
   //    strncat_s( dest, _countof(dest), "dachshunds", 15 );
   // Instead of causing a buffer overrun, strncat_s invokes
   // the invalid parameter handler.
   // If secure template overloads were disabled, strncat would
   // append "dachshunds" and overrun the dest buffer.
   printf_s( "    new contents of dest: '%s'\n", dest );
}

void myInvalidParameterHandler(
   const wchar_t* expression,
   const wchar_t* function, 
   const wchar_t* file, 
   unsigned int line, 
   uintptr_t pReserved)
{
   wprintf_s(L"Invalid parameter handler invoked: %s\n", expression);
}

int main( void )
{
   _invalid_parameter_handler oldHandler, newHandler;

   newHandler = myInvalidParameterHandler;
   oldHandler = _set_invalid_parameter_handler(newHandler);
   // Disable the message box for assertions.
   _CrtSetReportMode(_CRT_ASSERT, 0);

   Examples();
}