strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_lstrncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Aggiunge caratteri a una stringa.Appends characters to a string. Queste versioni di strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l includono miglioramenti per la sicurezza, come descritto in Funzionalità di sicurezza in CRT.These versions of strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l have security enhancements, as described in Security Features in the CRT.

Importante

mbsncat_s e mbsncat_s_l non può essere usata nelle applicazioni eseguite in Windows Runtime._mbsncat_s and _mbsncat_s_l cannot be used in applications that execute in the Windows Runtime. Per altre informazioni, vedere Funzioni CRT non supportate nelle app della piattaforma UWP (Universal Windows Platform).For more information, see CRT functions not supported in Universal Windows Platform apps.

SintassiSyntax

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

ParametriParameters

strDeststrDest
Stringa di destinazione con terminazione Null.Null-terminated destination string.

numberOfElementsnumberOfElements
Dimensioni del buffer di destinazione.Size of the destination buffer.

strSourcestrSource
Stringa di origine con terminazione null.Null-terminated source string.

countcount
Numero di caratteri da aggiungere o _TRUNCATE.Number of characters to append, or _TRUNCATE.

localelocale
Impostazioni locali da usare.Locale to use.

Valore restituitoReturn Value

Restituisce 0 in caso di esito positivo e un codice di errore in caso di errore.Returns 0 if successful, an error code on failure.

Condizioni di erroreError Conditions

strDestinationstrDestination numberOfElementsnumberOfElements strSourcestrSource Valore restituitoReturn value Contenuto di strDestinationContents of strDestination
NULL o senza terminazioneNULL or unterminated qualsiasiany qualsiasiany EINVALEINVAL non modificatonot modified
qualsiasiany qualsiasiany NULLNULL EINVALEINVAL non modificatonot modified
qualsiasiany 0 o troppo piccolo0, or too small qualsiasiany ERANGEERANGE non modificatonot modified

NoteRemarks

Queste funzioni tenta di aggiungere il primo 1!d caratteri strSource alla fine della strDest, dove 1!d è il minore dei count e la lunghezza di strSource.These functions try to append the first D characters of strSource to the end of strDest, where D is the lesser of count and the length of strSource. Se aggiunta quelli 1!d caratteri contenuta interamente strDest (la cui dimensione è specificata come numberOfElements) e ancora lasciare spazio per una terminazione null, quindi tali caratteri vengono aggiunti, iniziando in corrispondenza di terminazione null di originale strDest, e un carattere di terminazione null nuovo accodati; in caso contrario, strDest[0] è impostato per il carattere null e il parametro non valido gestore viene richiamato, come descritto in convalida dei parametri.If appending those D characters will fit within strDest (whose size is given as numberOfElements) and still leave room for a null terminator, then those characters are appended, starting at the original terminating null of strDest, and a new terminating null is appended; otherwise, strDest[0] is set to the null character and the invalid parameter handler is invoked, as described in Parameter Validation.

Esiste un'eccezione a quanto indicato nel paragrafo precedente.There is an exception to the above paragraph. Se conteggio viene truncate quindi quanti più strSource come adatta alla pagina viene aggiunto al strDest lasciando spazio sufficiente per accodare un terminazione null.If count is _TRUNCATE then as much of strSource as will fit is appended to strDest while still leaving room to append a terminating null.

Ad esempio,For example,

char dst[5];
strncpy_s(dst, _countof(dst), "12", 2);
strncat_s(dst, _countof(dst), "34567", 3);

significa che, ti chiediamo strncat_s per aggiungere tre caratteri a due caratteri in un buffer di cinque caratteri; in tal nessuno spazio per una terminazione null, pertanto strncat_s zeri out la stringa e chiama il gestore di parametri non validi.means that we are asking strncat_s to append three characters to two characters in a buffer five characters long; this would leave no space for the null terminator, hence strncat_s zeroes out the string and calls the invalid parameter handler.

Se è necessario un comportamento di troncamento, usare truncate o regolare il dimensioni parametro conseguenza:If truncation behavior is needed, use _TRUNCATE or adjust the size parameter accordingly:

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

oppureor

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

In tutti i casi, la stringa risultante termina con un carattere Null.In all cases, the resulting string is terminated with a null character. Se la copia avviene tra stringhe che si sovrappongono, il comportamento non è definito.If copying takes place between strings that overlap, the behavior is undefined.

Se strSource oppure strDest è NULL, oppure è numberOfElements è uguale a zero, viene richiamato il gestore di parametri non validi, come descritto in Convalida dei parametri .If strSource or strDest is NULL, or is numberOfElements is zero, the invalid parameter handler is invoked, as described in Parameter Validation . Se l'esecuzione può continuare, la funzione restituisce EINVAL senza modificare i relativi parametri.If execution is allowed to continue, the function returns EINVAL without modifying its parameters.

wcsncat_s e mbsncat_s sono versioni a caratteri wide e caratteri multibyte di strncat_s.wcsncat_s and _mbsncat_s are wide-character and multibyte-character versions of strncat_s. Gli argomenti di stringa e valore restituito del wcsncat_s sono caratteri wide, mentre quelli di stringhe mbsncat_s sono stringhe a caratteri multibyte.The string arguments and return value of wcsncat_s are wide-character strings; those of _mbsncat_s are multibyte-character strings. A parte ciò, queste tre funzioni si comportano in modo identico.These three functions behave identically otherwise.

Il valore di output è interessato dalla configurazione dell'impostazione delle LC_CTYPE categoria delle impostazioni locali, vedere setlocale per altre informazioni.The output value is affected by the setting of the LC_CTYPE category setting of the locale; see setlocale for more information. Le versioni di queste funzioni senza il suffisso _l usano le impostazioni locali correnti per questo comportamento dipendente dalle impostazioni locali. Le versioni con il suffisso _l sono identiche, ma usano il parametro passato alle impostazioni locali.The versions of these functions without the _l suffix use the current locale for this locale-dependent behavior; the versions with the _l suffix are identical except that they use the locale parameter passed in instead. Per altre informazioni, vedere Locale.For more information, see Locale.

In C++ l'utilizzo di queste funzioni è semplificato dagli overload dei modelli. Gli overload possono dedurre la lunghezza del buffer automaticamente (eliminando la necessità di specificare un argomento di dimensione) e possono sostituire automaticamente le funzioni precedenti e non sicure con le controparti più recenti e sicure.In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. Per altre informazioni, vedere Secure Template Overloads.For more information, see Secure Template Overloads.

Le versioni di debug di queste funzioni riempiono innanzitutto il buffer con 0xFD.The debug versions of these functions first fill the buffer with 0xFD. Per disabilitare questo comportamento, usare _CrtSetDebugFillThreshold.To disable this behavior, use _CrtSetDebugFillThreshold.

Mapping di routine di testo genericoGeneric-Text Routine Mappings

Routine TCHAR.HTCHAR.H routine _UNICODE e _MBCS non definiti_UNICODE & _MBCS not defined _MBCS definito_MBCS defined _UNICODE definito_UNICODE defined
tcsncat_s_tcsncat_s strncat_sstrncat_s _mbsnbcat_s_mbsnbcat_s wcsncat_swcsncat_s
tcsncat_s_l_tcsncat_s_l _strncat_s_l_strncat_s_l _mbsnbcat_s_l_mbsnbcat_s_l _wcsncat_s_l_wcsncat_s_l

_strncat_s_l e _wcsncat_s_l non dispone di alcuna dipendenza dalle impostazioni locali, vengono fornite soltanto per tcsncat_s_l._strncat_s_l and _wcsncat_s_l have no locale dependence; they are only provided for _tcsncat_s_l.

RequisitiRequirements

RoutineRoutine Intestazione obbligatoriaRequired header
strncat_sstrncat_s <string.h><string.h>
wcsncat_swcsncat_s <string.h> o <wchar.h><string.h> or <wchar.h>
mbsncat_s, mbsncat_s_l_mbsncat_s, _mbsncat_s_l <mbstring.h><mbstring.h>

Per altre informazioni sulla compatibilità, vedere Compatibilità.For additional compatibility information, see Compatibility.

EsempioExample

// 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: ''

Vedere ancheSee also

Modifica di stringheString Manipulation
Impostazioni localiLocale
Interpretazione di sequenze di caratteri multibyteInterpretation of Multibyte-Character Sequences
_mbsnbcat, _mbsnbcat_l_mbsnbcat, _mbsnbcat_l
strcat, wcscat, _mbscatstrcat, wcscat, _mbscat
strcmp, wcscmp, _mbscmpstrcmp, wcscmp, _mbscmp
strcpy, wcscpy, _mbscpystrcpy, wcscpy, _mbscpy
strncmp, wcsncmp, _mbsncmp, _mbsncmp_lstrncmp, wcsncmp, _mbsncmp, _mbsncmp_l
strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_lstrncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l
_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l
strrchr, wcsrchr, _mbsrchr, _mbsrchr_lstrrchr, wcsrchr, _mbsrchr, _mbsrchr_l
_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l
strspn, wcsspn, _mbsspn, _mbsspn_lstrspn, wcsspn, _mbsspn, _mbsspn_l