strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l

Artículo
06/09/2015

Anexa caracteres de una cadena. Hay disponibles versiones más seguras de estas funciones; vea strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l.

Importante

_mbsncat y _mbsncat_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.

char *strncat(
   char *strDest,
   const char *strSource,
   size_t count 
);
wchar_t *wcsncat(
   wchar_t *strDest,
   const wchar_t *strSource,
   size_t count 
);
unsigned char *_mbsncat(
   unsigned char *strDest,
   const unsigned char *strSource,
   size_t count
);
unsigned char *_mbsncat_l(
   unsigned char *strDest,
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
);
template <size_t size>
char *strncat(
   char (&strDest)[size],
   const char *strSource,
   size_t count 
); // C++ only
template <size_t size>
wchar_t *wcsncat(
   wchar_t (&strDest)[size],
   const wchar_t *strSource,
   size_t count 
); // C++ only
template <size_t size>
unsigned char *_mbsncat(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count
); // C++ only
template <size_t size>
unsigned char *_mbsncat_l(
   unsigned char (&strDest)[size],
   const unsigned char *strSource,
   size_t count,
   _locale_t locale
); // C++ only

Parámetros

strDest
Cadena de destino terminada en NULL.
strSource
Cadena de origen terminada en NULL.
count
Número de caracteres que se van a anexar.
locale
Configuración regional que se va a usar.

Valor devuelto

Devuelve un puntero a la cadena de destino. No se reserva ningún valor devuelto para indicar un error.

Comentarios

La función strncat anexa, como máximo, los primeros count caracteres de strSource a strDest. El carácter inicial de strSource sobrescribe el carácter nulo de terminación de strDest. Si hay un carácter nulo en strSource antes de que se anexen count caracteres, _strncat anexa todos los caracteres de strSource, hasta el carácter nulo. Si count es mayor que la longitud de strSource, se usa la longitud de strSource en lugar de count. 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.

Nota sobre la seguridad
strncat no comprueba si espacio suficiente en strDest, por lo que podría producirse un problema de saturaciones del búfer.Tenga presente que count limita el número de caracteres que se anexan, no el tamaño de strDest.Vea el ejemplo siguiente.Para obtener más información, vea Evitar saturaciones del búfer.

wcsncat y _mbsncat son versiones de caracteres anchos y multibyte de strncat. Los argumentos de cadena y el valor devuelto de wcsncat son cadenas de caracteres anchos; los de _mbsncat 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++, estas funciones tienen sobrecargas de plantilla. Para obtener más información, vea Sobrecargas de plantilla seguras.

Asignaciones de rutina de texto genérico

Rutina TCHAR.H	_UNICODE y _MBCS no definidos	_MBCS definido	_UNICODE definido
_tcsncat	strncat	_mbsnbcat	wcsncat
_tcsncat_l	_strncat_l	_mbsnbcat_l	_wcsncat_l

Nota

_strncat_l y _wcsncat_l no dependen de la configuración regional y no están diseñadas para llamarlas directamente.Se proporcionan solo para el uso interno por parte de _tcsncat_l.

Requisitos

Rutina	Encabezado necesario
strncat	<string.h>
wcsncat	<string.h> o <wchar.h>
_mbsncat	<mbstring.h>
_mbsncat_l	<mbstring.h>

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

Ejemplo

// crt_strncat.c
// Use strcat and strncat to append to a string.
#include <stdlib.h>

#define MAXSTRINGLEN 39

char string[MAXSTRINGLEN+1];
// or char *string = malloc(MAXSTRINGLEN+1);

void BadAppend( char suffix[], int n )
{
   strncat( string, suffix, n );
}

void GoodAppend( char suffix[], size_t n )
{
   strncat( string, suffix, __min( n, MAXSTRINGLEN-strlen(string)) );
}

int main( void )
{
   string[0] = '\0';
   printf( "string can hold up to %d characters\n", MAXSTRINGLEN );

   strcpy( string, "This is the initial string!" );
   // concatenate up to 20 characters...
   BadAppend( "Extra text to add to the string...", 20 );
   printf( "After BadAppend :  %s (%d chars)\n", string, strlen(string) );

   strcpy( string, "This is the initial string!" );
   // concatenate up to 20 characters...
   GoodAppend( "Extra text to add to the string...", 20 );
   printf( "After GoodAppend:  %s (%d chars)\n", string, strlen(string) );
}

Resultados

string can hold up to 39 characters
After BadAppend :  This is the initial string!Extra text to add to (47 chars)
After GoodAppend:  This is the initial string!Extra text t (39 chars)

Observe que BadAppend produjo una saturación del búfer.