strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Artículo
04/10/2013

Agregue los caracteres en una cadena.Éstas son versiones de strncat, _strncat_l, wcsncat, wcsncat_l, _mbsncat _mbsncat_l con mejoras de seguridad como se describe en Características de seguridad en CRT.

Importante
_mbsncat_s y _mbsncat_s_l no se pueden 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 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 terminada en null de destino.
[in]numberOfElements
Tamaño del búfer de destino.
[in]strSource
Cadena terminada en null de origen.
[in]count
Número de caracteres que se va a anexar, o _TRUNCATE.
[in] locale
Configuración regional a utilizar.

Valor devuelto

Devuelve 0 si es correcto, un código de error del error.

Condiciones de error

strDestination	numberOfElements	strSource	Valor devuelto	Contenido de strDestination
NULL o e indefinida	any	any	EINVAL	no modificado
any	any	NULL	EINVAL	no modificado
any	0, demasiado pequeño	any	ERANGE	no modificado

Comentarios

Intento de estas funciones para anexar los primeros caracteres de D de strSource al final de strDest, donde es menos D de count y longitud de strSource.Si anexar esos caracteres de D cabe dentro de strDest (cuyo tamaño se da como numberOfElements) y todavía salir de sitio para un terminador nulo, se anexa a esos caracteres, empezando en el original que termina null de strDest, y se anexa una nueva null final; si no, strDest[0] se establece en el carácter null y el controlador no válido de parámetro se invoca, como se describe en Validación de parámetros.

Hay una excepción al párrafo anterior.Si count es _TRUNCATE a continuación en muchos de strSource que caben se anexa a strDest mientras todavía sale del sitio de anexar un carácter null final.

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 para anexar tres caracteres a dos caracteres de caracteres de un búfer cinco long; esto no permitiría ningún espacio para el terminador, por tanto los ceros nulos de strncat_s comentario la cadena y llama al controlador no válido del parámetro.

Si el comportamiento del truncamiento es necesario, utilice _TRUNCATE o ajustar el parámetro de size como consecuencia:

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

o bien

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

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

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

wcsncat_s y _mbsncat_s son versiones de caracteres anchos y de multibyte- carácter de strncat_s.Los argumentos de cadena y el valor devuelto de wcsncat_s son cadenas de caracteres; las de _mbsncat_s son cadenas de multibyte- carácter.Estas tres funciones se comportan exactamente igual de otra manera.

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

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 0xFD.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
_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 información adicional de compatibilidad, vea Compatibilidad en la Introducción.

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