strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Articolo
03/26/2013

Aggiungere i caratteri in una stringa.Queste sono versioni di strncat, _strncat_l, wcsncat, wcsncat_l, _mbsncat _mbsncat_l con 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 eseguite nelle finestre 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	Contenuti 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 caratteri di D di strSource alla fine di strDest, dove le D è minore di count e la lunghezza di strSource.Se aggiungere tali caratteri di D entrerà in strDest (la cui dimensione viene fornita come numberOfElements) e successivamente lasciare spazio a un terminatore null, quindi questi caratteri vengono aggiunti, inizianti a null originale di terminazione di strDeste un nuovo di terminazione null viene aggiunto; in caso contrario, strDest[0] è impostato sul carattere null e il gestore non valido di parametro viene richiamato, come descritto in Convalida dei parametri.

Esiste un'eccezione al paragrafo sopra.Se count è _TRUNCATE quindi così molto di strSource quanto si estenderà viene aggiunto a strDest pur lascia aggiungere un 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 che ne richiede a strncat_s per aggiungere lunga tre caratteri a due caratteri tra i caratteri di un buffer cinque; ciò non lascerebbe spazio per il terminatore null, gli zeri di strncat_s alla stringa e chiama il gestore non valido di parametro.

Se il comportamento del troncamento è necessaria, utilizzare _TRUNCATE o modificare il parametro di size di seguito:

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 di risultato termina con un carattere null.Se copiare è compresa tra stringhe che si sovrappongono, il comportamento è definito.

Se strSource o strDest è NULL, o è numberOfElements è zero, il gestore non valido di parametro viene richiamato, come descritto in Convalida dei parametri.Se l'esecuzione è consentita per 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 di wcsncat_s sono stringhe di caratteri estesi, tali 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 Assicurarsi che gli overload del modello.

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

Mapping di routine a Testo generico

TCHAR.H routine	_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 dispongono di dipendenza delle 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à nell'introduzione.

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();
}