strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Makale
06/09/2015

Bir dizeye karakterler ekler.Bu strncat, _strncat_l, wcsncat, wcsncat_l, _mbsncat _mbsncat_l sürümlerinde CRT'deki Güvenlik Özellikleri içinde açıklandığı gibi güvenlik geliştirmeleri mevcut olabilir.

Önemli
_mbsncat_s ve _mbsncat_s_l Windows Çalışma Zamanı'nda yürütülen uygulamalarda kullanılamazlar.Daha fazla bilgi için bkz /ZW ile desteklenmeyen CRT işlevleri.

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

Parametreler

[out] strDest
Null ile sonlandırılmış hedef dize.
[in]numberOfElements
Hedef arabelleğin boyutu.
[in]strSource
Null ile sonlandırılmış kaynak dizesi.
[in]count
Eklemek için karakter sayısını veya _TRUNCATE.
[in] locale
Kullanılacak yerel ayar.

Dönüş Değeri

Başarılı olursa 0 değerini döndürür başarısız olduğunda bir hata kodu.

Hata Durumları

strDestination	numberOfElements	strSource	Dönüş değeri	strDestination içeriği
NULLveya Sonlandırılmamış	any	any	EINVAL	değiştirilmemiş
any	any	NULL	EINVAL	değiştirilmemiş
any	0 veya çok küçük	any	ERANGE	değiştirilmemiş

Notlar

Bu işlevlerin ilk dosyaya eklenmeye çalışılacak D karakter strSource sonuna kadar strDest, nerede D küçük olanı ise count ve uzunluğu, strSource.Bu ekleme, D karakterleri içinde uygun strDest (boyutu olarak verilir numberOfElements) bırakıp, null sonlandırma özgün başlayan bu karakterler eklenir sonra hala null bir sonlandırıcıya yer strDestve yeni bir sonunda boş eklenir; Aksi takdirde, strDest[0] ayarlanır null karakteri ve geçersiz bir parametre için işleyici, açıklandığı gibi çağrılır Parametre Doğrulama.

Yukarıdaki paragrafı bir istisna vardır.Yoksa count olan _TRUNCATE sonra çok strSource sığdırmak için eklenen strDest hala bir sonlandırma ekleneceği yer boş bırakarak sırasında.

Örnek:

char dst[5];

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

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

Biz soran anlamına gelir strncat_s üç karakter arabelleği beş karakter uzunluğunda; iki karakter eklemek için Bu null Sonlandırıcı için yer yok Bu yüzden bırakabilir strncat_s zeroes dizesi ve geçersiz parametre işleyiciyi çağırır.

Kesme davranışı gerekirse kullanmak _TRUNCATE veya size parametre buna göre:

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

veya

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

Her durumda, sonuç dizesi null karakteriyle sonlandırılır.Çakışan dizeler arasında kopyalama yer alırsa davranış tanımsızdır.

Varsa strSource veya strDest olan NULL, ya da numberOfElements sıfır açıklandığı gibi geçersiz bir parametre işleyici çağrılır Parametre Doğrulama .İşlev verir yürütülmesine devam etmek için izin verilip verilmediğini, EINVAL parametrelerini değiştirme olmadan.

wcsncat_s ve _mbsncat_s, strncat_s öğesinin geniş karakter ve çok baytlı karakter sürümleridir.Dize bağımsız değişkenleri ve wcsncat_s dönüş değeri geniş karakterli dizelerdir; _mbsncat_s dizeleri çok baytlı karakter dizeleridir.Bu üç işlev, aynı şekilde davranır.

Çıkış değeri, yerel ayarın LC_CTYPE kategori ayarından etkilenir; daha fazla bilgi için, bkz. setlocale.Bu işlevlerin, _l sonekine sahip olmayan sürümleri, yerel ayara bağlı davranışı için, geçerli yerel ayarı kullanır; _l sonekine sahip sürümler, bunun yerine iletilmiş yerel ayar parametresini kullanması hariç aynıdır.Daha fazla bilgi için bkz. Yerel Ayar.

C++ dilinde bu işlevleri kullanmak şablon aşırı yüklemeleriyle basitleştirilmiştir; aşırı yüklemeler arabellek uzunluğunu otomatik olarak çıkarabilir (bir boyut bağımsız değişkeni belirtme gereksinimi ortadan kalkar) ve bunlar otomatik olarak eski ve güvenli olmayan işlevlerle daha yeni ve güvenli karşılıklarını değiştirir.Daha fazla bilgi için bkz. Güvenli Şablon Aşırı Yüklemeleri.

Bu işlevlerin hata ayıklama sürümleri arabelleği ilk önce 0xFD ile doldurur.Bu davranışı devre dışı bırakmak için _CrtSetDebugFillThreshold kullanın.

Genel Metin Yordam Eşleşmeleri

TCHAR.H yordamı	_UNICODE & _MBCS tanımlanmamış	_MBCS tanımlanmış	_UNICODE tanımlanmış
_tcsncat_s	strncat_s	_mbsnbcat_s	wcsncat_s
_tcsncat_s_l	_strncat_s_l	_mbsnbcat_s_l	_wcsncat_s_l

_strncat_s_lve _wcsncat_s_l sahip hiçbir yerel bağımlılığı; Bunlar yalnızca için sağlanan _tcsncat_s_l.

Gereksinimler

Yordam	Gerekli başlık
strncat_s	<string.h>
wcsncat_s	<string.h> or <wchar.h>
_mbsncat_s, _mbsncat_s_l	<mbstring.h>

Ek uyumluluk bilgileri için bkz. Uyumluluk.

Örnek

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