`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`

Articolo
10/12/2023

Aggiunge caratteri a una stringa. Queste versioni di strncat, _strncat_l_wcsncat_lwcsncat, _mbsncat, _mbsncat_l includono miglioramenti della sicurezza, come descritto in Funzionalità di sicurezza in CRT.

Importante

_mbsncat_s e _mbsncat_s_l non possono essere usati nelle applicazioni eseguite in Windows Runtime. Per altre informazioni, vedere Funzioni CRT non supportate nelle app della piattaforma UWP (Universal Windows Platform).

Sintassi

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

Parametri

strDest
Stringa di destinazione con terminazione Null.

numberOfElements
Dimensioni del buffer di destinazione.

strSource
Stringa di origine con terminazione null.

count
Numero di caratteri da aggiungere o _TRUNCATE.

locale
Impostazioni locali da usare.

Valore restituito

Restituisce 0 in caso di esito positivo e un codice di errore in caso di errore.

Condizioni di errore

`strDestination`	`numberOfElements`	`strSource`	Valore restituito	Contenuto di `strDestination`
`NULL` o senza terminazione	qualsiasi	qualsiasi	`EINVAL`	non modificato
qualsiasi	qualsiasi	`NULL`	`EINVAL`	non modificato
qualsiasi	0 o troppo piccolo	qualsiasi	`ERANGE`	non modificato

Osservazioni:

Queste funzioni tentano di aggiungere i primi D caratteri di strSource alla fine di strDest, dove D è il minore di count e la lunghezza di strSource. Se l'aggiunta di tali D caratteri verrà inserita all'interno strDest di (la cui dimensione viene specificata come numberOfElements) e lasciare spazio per un terminatore Null null, tali caratteri vengono accodati, a partire dall'originale null strDestdi terminazione e viene accodato un nuovo valore Null di terminazione; in caso contrario, strDest[0] viene impostato sul carattere Null e viene richiamato il gestore di parametri non validi, come descritto in Convalida dei parametri.

Esiste un'eccezione al paragrafo precedente. Se count è _TRUNCATE, viene aggiunto fino strSource a strDest quando rimane spazio per accodare un valore Null di terminazione.

Ad esempio,

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

significa che si chiede strncat_s di aggiungere tre caratteri a due caratteri in un buffer di cinque caratteri lunghi. Non lasciare spazio per il carattere di terminazione Null, quindi strncat_s zero la stringa e chiama il gestore di parametri non validi.

Se è necessario il comportamento di troncamento, usare _TRUNCATE o modificare il parametro count di conseguenza:

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

oppure

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

In tutti i casi, la stringa risultante termina con un carattere Null. Se la copia avviene tra stringhe che si sovrappongono, il comportamento non è definito.

Se strSource o strDest è o numberOfElements è NULLzero, viene richiamato il gestore di parametri non validi, come descritto in Convalida dei parametri . Se l'esecuzione può continuare, la funzione restituisce e EINVAL senza modificare i parametri.

wcsncat_s e _mbsncat_s sono versioni con caratteri wide e caratteri multibyte di strncat_s. Gli argomenti stringa e il valore restituito di wcsncat_s sono stringhe di caratteri wide. Gli argomenti e il valore restituito di sono stringhe di _mbsncat_s caratteri multibyte. A parte ciò, queste tre funzioni si comportano in modo identico.

Il valore di output è interessato dall'impostazione dell'impostazione LC_CTYPE della categoria delle impostazioni locali. Per ulteriori informazioni, vedere setlocale. Le versioni di queste funzioni senza il _l suffisso usano le impostazioni locali correnti per questo comportamento dipendente dalle impostazioni locali. Le versioni con il _l suffisso sono identiche, tranne che usano il parametro delle impostazioni locali passato. Per altre informazioni, vedere 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. Per altre informazioni, vedere Proteggere gli overload dei modelli.

Le versioni della libreria di debug di queste funzioni riempiono prima di tutto il buffer con 0xFE. Per disabilitare questo comportamento, usare _CrtSetDebugFillThreshold.

Per impostazione predefinita, lo stato globale di questa funzione è limitato all'applicazione. Per modificare questo comportamento, vedere Stato globale in CRT.

Mapping di routine di testo generico

Routine TCHAR.H	`_UNICODE` e `_MBCS` non definito	`_MBCS` Definito	`_UNICODE` Definito
`_tcsncat_s`	`strncat_s`	`_mbsnbcat_s`	`wcsncat_s`
`_tcsncat_s_l`	`_strncat_s_l`	`_mbsnbcat_s_l`	`_wcsncat_s_l`

_strncat_s_l e _wcsncat_s_l non hanno alcuna dipendenza dalle impostazioni locali; sono forniti solo per _tcsncat_s_l.

Requisiti

Ciclo	Intestazione obbligatoria
`strncat_s`	<string.h>
`wcsncat_s`	<string.h> o <wchar.h>
`_mbsncat_s`, `_mbsncat_s_l`	<mbstring.h>

Per altre informazioni sulla compatibilità, vedere Compatibility (Compatibilità).

Esempio

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

Vedi anche

Manipolazione delle stringhe
impostazioni locali
Interpretazione di sequenze di caratteri multibyte
_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

`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`

Sintassi

Parametri

Valore restituito

Condizioni di errore

Osservazioni:

Mapping di routine di testo generico

Requisiti

Esempio

Vedi anche

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive

strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Sintassi

Parametri

Valore restituito

Condizioni di errore

Osservazioni:

Mapping di routine di testo generico

Requisiti

Esempio

Vedi anche

Commenti e suggerimenti

Commenti e suggerimenti

Risorse aggiuntive

`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`