strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l

Anexa caracteres de una cadena. Hay disponibles versiones más seguras de estas funciones; consulte 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 Runtime. Para obtener más información, vea Funciones de CRT no admitidas en aplicaciones de la Plataforma universal de Windows.

Sintaxis

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.

Importante

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. Observe el ejemplo siguiente. Para obtener más información, consulte 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 argumentos de cadena y el valor devuelto 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. Para obtener más información, vea setlocale. Las versiones de estas funciones sin el sufijo _l utilizan la configuración regional actual en el comportamiento que depende de esta configuración regional. Las versiones con el sufijo _l son idénticas, salvo que usan el parámetro de configuración regional que se pasa. Para obtener más información, vea Locale.

En C++, estas funciones tienen sobrecargas de plantilla. Para obtener más información, consulte Sobrecargas de plantilla seguras.

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
_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

Routine	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, consulte 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) );
}

Output

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)

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

Consulte también

Manipulación de cadenas
_mbsnbcat, _mbsnbcat_l
strcat, wcscat, _mbscat
strcmp, wcscmp, _mbscmp
strcpy, wcscpy, _mbscpy
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
_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l
strspn, wcsspn, _mbsspn, _mbsspn_l
Configuración regional
Interpretación de secuencias de caracteres de varios bytes