strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l

Makale
03/27/2013

Karakterler için bir dize ekler.Sürümleri bunlar strncat, _strncat_l, wcsncat, wcsncat_l, _mbsncat _mbsncat_l açıklandığı gibi güvenlik geliştirmeleri ile crt güvenlik özellikleri.

Önemli
_mbsncat_sve _mbsncat_s_l Windows çalışma zamanı yürütme uygulamalarda kullanılamaz.Daha fazla bilgi için bkz: /zw ile desteklenmeyen crt işlevlerinin.

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

[çıkış]strDest
Hedef boşlukla sonlandırılmış dize.
[in]numberOfElements
Hedef arabelleğin boyutudur.
[in]strSource
Kaynak boşlukla sonlandırılmış dize.
[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 döndürür başarısız olduğunda bir hata kodu.

Hata koşulları

strDestination	numberOfElements	strSource	Dönüş değeri	İçeriğistrDestination
NULLveya sonlandırılmamış	herhangi bir	herhangi bir	EINVAL	modifiye edilmemiş
herhangi bir	herhangi bir	NULL	EINVAL	modifiye edilmemiş
herhangi bir	0 veya çok küçük	herhangi bir	ERANGE	modifiye edilmemiş

Notlar

İlk eklemek bu işlevleri deneyin D karakterini strSource sonuna kadar strDest, D en küçük olan count ve uzunluğunu strSource.Bu ekleme, D karakter içinde sığacak strDest (boyutu olarak verilir numberOfElements) bırakıp, null sonlandırma özgün başlayan bu karakterler eklenir sonra yine de null bir sonlandırıcı için oda strDestve yeni bir sonunda boş eklenir; Aksi halde, strDest[0] olarak null karakteri ve geçersiz bir parametre için işleyici, açıklandığı gibi çağrılır Parametre doğrulama.

Yukarıdaki paragraf için bir özel durum söz konusudur.count Olan _TRUNCATE sonra kadarını strSource sığdırmak için eklenen strDest bir sonlandırma ekleneceği yer hala 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 alan için null Sonlandırıcı yok bu yüzden bırakabilir strncat_s sıfırlardan dizesi ve geçersiz parametre işleyiciyi çağırır.

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

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

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

Tüm durumlarda, sonuç dizesi boş karakter ile sonlandırılır.Kopyalama, üst üste dizeler arasında yer alıyorsa, davranışı tanımsızdır.

strSource Veya strDest olan NULL, ya da numberOfElements sıfırsa, 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_sve _mbsncat_s geniş karakter ve çok baytlı karakter sürümleri strncat_s.Dize bağımsız değişkenleri ve dönüş değeri wcsncat_s geniş karakter dizesidir; _mbsncat_s çok baytlı karakter dizeleridir.Bu üç işlevi aynı şekilde aksi davranır.

Çıkış değeri ayarı tarafından etkilenen LC_CTYPE ; bölgesel ayar kategorisi bkz: setlocale daha fazla bilgi için.Bu işlevler sürümlerini _l soneki kullanan geçerli yerel ayarı için bu yerel ayara bağımlı davranışı; sürümleri ile _l sonek dışında bunun yerine geçirilen yerel ayar parametresi kullandıkları aynı.Daha fazla bilgi için bkz. Yerel ayar.

C++'da, bu işlevleri kullanarak şablon aşırı yükleme tarafından Basitleştirilmiş; aşırı arabellek uzunluğu otomatik olarak çıkarabilir (size baðýmsýz deðiþkeni belirtmek gereğini ortadan kaldırır) ve bunların daha eski, güvenli olmayan işlevler daha yeni ve güvenli karşılıklarıyla otomatik olarak değiştirebilirsiniz.Daha fazla bilgi için bkz. Güvenli şablon aşırı yükleme.

Bu işlevleri hata ayıklama sürümleri arabellek 0xFD ile doldurun.Bu davranışı devre dışı bırakmak için _CrtSetDebugFillThreshold.

Genel metin eşlemeleri yordamına girildi

TCHAR.H yordamına girildi	_UNICODE & _mbcs tanımlanmamış	Tanımlanan _mbcs	Tanımlanan _UNICODE
_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 otomatikleştirmekle; Bunlar yalnızca için sağlanan _tcsncat_s_l.

Gereksinimler

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

Ek uyumluluk bilgileri için bkz: Uyumluluk giriş.

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