strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Articolo
06/09/2015

Aggiunge caratteri a una stringa. Queste versioni di strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l contengono i miglioramenti della sicurezza come descritto in Funzionalità di sicurezza in CRT.

Importante

_mbsncat_s e _mbsncat_s_l non possono essere utilizzati nelle applicazioni che vengono eseguite in Windows Runtime.Per ulteriori informazioni, vedere Funzioni CRT non supportate 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

Parametri

[out] strDest
Stringa di destinazione con terminazione null.
[in]numberOfElements
Dimensione del buffer di destinazione.
[in]strSource
Stringa di origine con terminazione null.
[in]count
Numero di caratteri da aggiungere, o _TRUNCATE.
[in] locale
Impostazioni locali da utilizzare.

Valore restituito

Restituisce 0 se ha esito positivo, un codice di errore in caso di errore.

Condizioni di errore

strDestination	numberOfElements	strSource	Valore restituito	Contenuto di strDestination.
NULL o non terminato	any	any	EINVAL	non modificato
any	any	NULL	EINVAL	non modificato
any	0 o troppo piccolo	any	ERANGE	non modificato

Note

Queste funzioni tenta di aggiungere i primi D caratteri di strSource alla fine di strDest, dove D è minore di count e della lunghezza di strSource. Se si aggiungono D caratteri che verranno adattati in strDest (la cui dimensione viene fornita come numberOfElements) e lasciando ancora spazio per il terminatore null, questi caratteri vengono aggiunti, a partire dalla terminazione null originaria di strDest, alla quale viene aggiunta una nuova terminazione null; tuttavia, strDest[0] viene impostato sul carattere null e viene richiamato il gestore di parametro non valido, come descritto in Convalida dei parametri.

Si verifica un'eccezione al paragrafo precedente. Se count è _TRUNCATE gran parte di strSource si estenderà e verrà aggiunta a strDest in cui è possibile aggiungere lo spazio di terminazione null.

Di seguito è riportato un esempio:

char dst[5];

strncpy_s(dst, _countof(dst), "12", 2);

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

indica la richiesta di strncat_s di aggiungere tre caratteri a due caratteri in un buffer di lunghezza cinque caratteri; ciò non lascerebbe spazio per il terminatore null, perciò strncat_s azzera la stringa e invoca il gestore di parametro non valido.

Se il comportamento del troncamento è necessario, utilizzare _TRUNCATE o modificare il parametro size 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 risultate termina con un carattere null. Se la copia avviene tra stringhe che si sovrappongono, il comportamento non è definito.

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

wcsncat_s e _mbsncat_s sono versioni a caratteri di tipo "wide" e di caratteri multibyte di strncat_s. Gli argomenti della stringa e il valore restituito da wcsncat_s sono stringhe di caratteri di tipo "wide", quelli di _mbsncat_s sono stringhe di caratteri multibyte. Altrimenti queste tre funzioni si comportano in modo identico.

Il valore di output è interessato dall'impostazione dell'impostazione di categoria LC_CTYPE delle impostazioni locali; vedere setlocale per ulteriori informazioni. Le versioni di queste funzioni senza il suffisso _l utilizzano le impostazioni locali correnti per il comportamento dipendente dalle impostazioni locali; le versioni con il suffisso _l sono identiche, ad eccezione del fatto che utilizzano il parametro delle impostazioni locali che viene passato. Per ulteriori informazioni, vedere Impostazioni locali.

In C++, l'utilizzo di queste funzioni è semplificato dagli overload dei modelli; gli overload possono dedurre la lunghezza del buffer automaticamente (che elimina la necessità di specificare un argomento di dimensione) e possono sostituire automaticamente le funzioni precedenti, quelle non sicure alle più recenti e le controparti sicure. Per ulteriori informazioni, vedere Overload di modelli sicuri.

La versione di debug di queste funzioni per prima cosa riempiono il buffer con il valore 0xFD. Per disattivare questo comportamento, utilizzare _CrtSetDebugFillThreshold.

Mapping di routine su testo generico

Routine TCHAR.H	_UNICODE & _MBCS non definiti	_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 dipendenza dalle impostazioni locali; vengono forniti solo per _tcsncat_s_l.

Requisiti

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

Per ulteriori informazioni sulla compatibilità, vedere 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();
}