Aracılığıyla paylaş

_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l

  • Makale

Biçimlendirilmiş verileri bir dizeye yazar. Bu işlevler, _snprintfCRT'dekisnprintf Güvenlik özellikleri bölümünde açıklanan güvenlik geliştirmelerine sahip , , , _snwprintf, _snwprintf_lsürümleridir. _snprintf_l

Sözdizimi

int _snprintf_s(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format [,
   argument] ...
);

int _snprintf_s_l(
   char *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const char *format,
   _locale_t locale [,
   argument] ...
);

int _snwprintf_s(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format [,
   argument] ...
);

int _snwprintf_s_l(
   wchar_t *buffer,
   size_t sizeOfBuffer,
   size_t count,
   const wchar_t *format,
   _locale_t locale [,
   argument] ...
);

template <size_t size>
int _snprintf_s(
   char (&buffer)[size],
   size_t count,
   const char *format [,
   argument] ...
); // C++ only

template <size_t size>
int _snwprintf_s(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format [,
   argument] ...
); // C++ only

Parametreler

buffer
Çıktı için depolama konumu.

sizeOfBuffer
Çıktı için depolama konumunun boyutu. alan işlevlerin bayt cinsinden boyutu ve kullananlar wchar_tiçin sözcükler. char

count
Yazacak karakter sayısı üst sınırı. öğesini alan wchar_tişlevler için, yazacak en fazla geniş karakter sayısıdır. Veya ._TRUNCATE

format
Biçim denetimi dizesi.

argument
İsteğe bağlı bağımsız değişkenler.

locale
Kullanılacak yerel ayar.

Dönüş değeri

Sonlandırıcı NULLdahil değil, yazılan karakter sayısı. Bir çıkış hatası oluşursa negatif bir değer döndürülür. Ayrıntılar için bkz . Davranış özeti .

Açıklamalar

İşlev, _snprintf_s içinde buffer veya daha az karakter biçimlendirip depolar count ve sonlandırıcı NULLbir ekler. Her bağımsız değişken (varsa) dönüştürülür ve içindeki formatilgili biçim belirtimine göre çıkış yapılır. Biçimlendirme, işlev ailesi ile printf tutarlıdır; bkz . Biçim belirtimi söz dizimi: printf ve wprintf işlevleri. Çakışan dizeler arasında kopyalama olursa davranış tanımsızdır.

Davranış özeti

Aşağıdaki tablo için:

len-Biçimlendirilmiş verilerin boyutu olsun. İşlev bir char arabellek alırsa boyut bayt cinsindendir. İşlev bir wchar_t arabellek alırsa, boyut 16 bit sözcük sayısını belirtir.

  • Karakterler, arabelleğe alınan char işlevlerin karakterlerine wchar_t ve arabelleğe alınan wchar_t işlevlere yönelik karakterlere başvururchar.
  • Geçersiz parametre işleyicisi hakkında daha fazla bilgi için bkz . Parametre Doğrulama.
Koşul Davranış Dönüş değeri errno Geçersiz parametre işleyicisini çağırır
Başarılı Belirtilen biçim dizesini kullanarak karakterleri arabelleğe yazar. Sonlandırıcı NULLdahil değil, yazılan karakter sayısı. Yok Hayır
Biçimlendirme sırasında kodlama hatası Dize tanımlayıcısı s, , Sveya Z, biçimlendirme belirtimi işleme durdurulursa. -1 EILSEQ (42) Hayır
Biçimlendirme sırasında kodlama hatası Karakter tanımlayıcısı c veya Cişleniyorsa geçersiz karakter atlanır. Yazılan karakter sayısı, atlanan karakter için artırılmıyor ve bu karakter için yazılan veri yok. Biçim belirtimi işleme, tanımlayıcıyı kodlama hatasıyla atladıktan sonra devam eder. Sonlandırıcı NULLdahil değil, yazılan karakter sayısı. EILSEQ (42) Hayır
buffer == NULLve ve sizeOfBuffer == 0count == 0 Hiçbir veri yazılmıştır. 0 Yok Hayır
buffer == NULLsizeOfBuffer != 0 ve veyacount != 0 Geçersiz parametre işleyicisi yürütülürken yürütme devam ederse, negatif bir değer ayarlar errno ve döndürür. -1 EINVAL (22) Yes
buffer != NULL ve sizeOfBuffer == 0 Hiçbir veri yazılmıştır. -1 EINVAL (22) Yes
count == 0 A NULL , arabelleğin başına yerleştirilir. -1 Yok Hayır
count < 0 Güvenli değil: değer işaretsiz olarak kabul edilir ve büyük olasılıkla arabelleğinden sonra gelen belleğin üzerine yazılmasıyla sonuçlanan büyük bir değer oluşturur. Sonlandırıcı NULLdahil değil, yazılan karakter sayısı. Yok Hayır
count < sizeOfBuffer ve len <= count Tüm veriler yazılır ve sonlandırıcı NULL eklenir. Yazılan karakter sayısı. Yok Hayır
count < sizeOfBuffer ve len > count İlk count karakterler yazılır ve sonlandırıcı NULL eklenir. -1 Yok Hayır
count >= sizeOfBuffer ve len < sizeOfBuffer Tüm veriler sonlandırıcı NULLile yazılır. Yazılan karakter sayısı. Yok Hayır
count >= sizeOfBufferve ve len >= sizeOfBuffercount != _TRUNCATE Geçersiz parametre işleyicisi yürütülürken yürütme devam ederse, öğesini ayarlar errnobuffer[0] == NULLve negatif bir değer döndürür. -1 ERANGE (34) Yes
count == _TRUNCATE ve len >= sizeOfBuffer Dizenin sığacak buffer kadar büyük bir kısmını ve sonlandırıcısını NULLyazar. -1 Yok Hayır
count == _TRUNCATE ve len < sizeOfBuffer Dizenin tamamını buffer içine sonlandırıcı NULLbir ile yazar. Sonlandırıcı dahil olmak üzere yazılmayan NULLkarakter sayısı. Yok Hayır
format == NULL Hiçbir veri yazılmıştır. Geçersiz parametre işleyicisi yürütülürken yürütme devam ederse, negatif bir değer ayarlar errno ve döndürür. -1 EINVAL (22) Yes

Bunlar ve diğer hata kodları hakkında bilgi için bkz. _doserrno, errno, _sys_errlistve _sys_nerr.

Önemli

format Kullanıcı tanımlı bir dize olmadığından emin olun.

Windows 10 sürüm 2004 'den (derleme 19041) printf başlayarak, işlev ailesi yuvarlama için IEEE 754 kurallarına göre tam olarak temsil edilebilir kayan nokta numaraları yazdırır. Windows'un önceki sürümlerinde, '5' ile biten tam olarak temsil edilebilir kayan nokta sayıları her zaman yukarı yuvarlanırdı. IEEE 754, en yakın çift rakama ("Bankacı Yuvarlama" olarak da bilinir) yuvarlamaları gerektiğini belirtir. Örneğin, hem hem de printf("%1.0f", 1.5) printf("%1.0f", 2.5) 2'ye yuvarlanmalıdır. Daha önce 1,5 2'ye, 2,5 ise 3'e yuvarlardı. Bu değişiklik yalnızca tam olarak temsil edilebilir sayıları etkiler. Örneğin, 2,35 (bellekte temsil edildiğinde 2,3500000000000000000008'e daha yakındır) 2,4'e kadar yuvarlanmaya devam eder. Bu işlevler tarafından yapılan yuvarlama artık tarafından fesetroundayarlanan kayan nokta yuvarlama moduna da dikkat eder. Daha önce yuvarlama her zaman davranışı seçmişti FE_TONEAREST . Bu değişiklik yalnızca Visual Studio 2019 sürüm 16.2 ve üzeri kullanılarak oluşturulan programları etkiler. Eski kayan nokta yuvarlama davranışını kullanmak için 'legacy_stdio_float_rounding.obj' ile bağlantı sağlayın.

_snwprintf_s , öğesinin _snprintf_sgeniş karakterli bir sürümüdür; işaretçi _snwprintf_s bağımsız değişkenleri geniş karakterli dizelerdir. içindeki _snwprintf_s kodlama hatalarının algılanması, içindekinden _snprintf_sfarklı olabilir. _snwprintf_sgibi swprintf_s, çıkışını türünde FILEbir hedef yerine bir dizeye yazar.

Bu işlevlerin sonekli _l sürümleri aynıdır, ancak geçerli iş parçacığı yerel ayarı yerine geçirilen yerel ayar parametresini kullanırlar.

C++'ta bu işlevlerin kullanılması şablon aşırı yüklemeleriyle basitleştirilir; aşırı yüklemeler arabellek uzunluğunu otomatik olarak çıkarabilir (boyut bağımsız değişkeni belirtme gereksinimini ortadan kaldırır) ve eski, güvenli olmayan işlevleri yeni ve güvenli karşılıklarıyla otomatik olarak değiştirebilir. Daha fazla bilgi için bkz . Güvenli şablon aşırı yüklemeleri.

Genel metin yordamı eşlemeleri

Tchar.h olağan _UNICODE ve _MBCS tanımlanmadı _MBCS tanımlanan _UNICODE tanımlanan
_sntprintf_s _snprintf_s _snprintf_s _snwprintf_s
_sntprintf_s_l _snprintf_s_l _snprintf_s_l _snwprintf_s_l

Gereksinimler

Yordam Gerekli başlık
_snprintf_s, _snprintf_s_l <stdio.h>
_snwprintf_s, _snwprintf_s_l <stdio.h> veya <wchar.h>

Daha fazla uyumluluk bilgisi için bkz . Uyumluluk.

Örnek

// crt_snprintf_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.

int snprintf_s_tester( const char * fmt, int x, size_t count )
{
   char dest[10];

   printf( "\n" );

   if ( count == _TRUNCATE )
      printf( "%zd-byte buffer; truncation semantics\n",
               _countof(dest) );
   else
      printf( "count = %zd; %zd-byte buffer\n",
               count, _countof(dest) );

   int ret = _snprintf_s( dest, _countof(dest), count, fmt, x );

   printf( "    new contents of dest: '%s'\n", dest );

   return ret;
}

void Examples()
{
   // formatted output string is 9 characters long: "<<<123>>>"
   snprintf_s_tester( "<<<%d>>>", 121, 8 );
   snprintf_s_tester( "<<<%d>>>", 121, 9 );
   snprintf_s_tester( "<<<%d>>>", 121, 10 );

   printf( "\nDestination buffer too small:\n" );

   snprintf_s_tester( "<<<%d>>>", 1221, 10 );

   printf( "\nTruncation examples:\n" );

   int ret = snprintf_s_tester( "<<<%d>>>", 1221, _TRUNCATE );
   printf( "    truncation %s occur\n", ret == -1 ? "did"
                                                  : "did not" );

   ret = snprintf_s_tester( "<<<%d>>>", 121, _TRUNCATE );
   printf( "    truncation %s occur\n", ret == -1 ? "did"
                                                  : "did not" );
   printf( "\nSecure template overload example:\n" );

   char dest[10];
   _snprintf( dest, 10, "<<<%d>>>", 12321 );
   // With secure template overloads enabled (see #defines
   // at top of file), the preceding line is replaced by
   //    _snprintf_s( dest, _countof(dest), 10, "<<<%d>>>", 12345 );
   // Instead of causing a buffer overrun, _snprintf_s invokes
   // the invalid parameter handler.
   // If secure template overloads were disabled, _snprintf would
   // write 10 characters and overrun the dest buffer.
   printf( "    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(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();
}


count = 8; 10-byte buffer
    new contents of dest: '<<<121>>'

count = 9; 10-byte buffer
    new contents of dest: '<<<121>>>'

count = 10; 10-byte buffer
    new contents of dest: '<<<121>>>'

Destination buffer too small:

count = 10; 10-byte buffer
Invalid parameter handler invoked: ("Buffer too small", 0)
    new contents of dest: ''

Truncation examples:

10-byte buffer; truncation semantics
    new contents of dest: '<<<1221>>'
    truncation did occur

10-byte buffer; truncation semantics
    new contents of dest: '<<<121>>>'
    truncation did not occur

Secure template overload example:
Invalid parameter handler invoked: ("Buffer too small", 0)
    new contents of dest: ''

Ayrıca bkz.

Akış G/Ç
sprintf, _sprintf_l, swprintf, _swprintf_l, , __swprintf_l
fprintf, _fprintf_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_l
scanf, _scanf_l, wscanf, _wscanf_l
sscanf, _sscanf_l, swscanf, _swscanf_l
vprintf işlevleri