Exportar (0) Imprimir
Expandir todo
and
div
eof
not
or
xor
Expandir Minimizar
Este artículo se tradujo de forma manual. Mueva el puntero sobre las frases del artículo para ver el texto original. Más información.
Traducción
Original

strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

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.

Nota importante 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

[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.

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

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.

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.

// 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();
}
Appending 4 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hi '
    new contents of dest: 'hi ther'

Appending 5 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hi '
    new contents of dest: 'hi there'

Appending 6 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hi '
    new contents of dest: 'hi there'

Destination buffer too small:

Appending 4 chars of 'there' to 10-byte buffer dest
    old contents of dest: 'hello '
Invalid parameter handler invoked: (L"Buffer is too small" && 0)
    new contents of dest: ''

Truncation examples:

Appending 'there' to 10-byte buffer dest with truncation semantics
    old contents of dest: 'hello '
    new contents of dest: 'hello the'
    truncation did occur

Appending '!' to 10-byte buffer dest with truncation semantics
    old contents of dest: 'hello '
    new contents of dest: 'hello !'
    truncation did not occur

Secure template overload example:
Invalid parameter handler invoked: (L"Buffer is too small" && 0)
    new contents of dest: ''

Adiciones de comunidad

AGREGAR
Mostrar:
© 2015 Microsoft