`vsnprintf`, `_vsnprintf`, `_vsnprintf_l`, `_vsnwprintf`, , `_vsnwprintf_l`

Bağımsız değişkenler listesine bir işaretçi kullanarak biçimlendirilmiş çıktı yazın. Bu işlevlerin daha güvenli sürümleri mevcuttur; Bkz. vsnprintf_s, _vsnprintf_s, , _vsnprintf_s_l_vsnwprintf_s_vsnwprintf_s_l, .

Sözdizimi

int vsnprintf(
   char *buffer,
   size_t count,
   const char *format,
   va_list argptr
);

int _vsnprintf(
   char *buffer,
   size_t count,
   const char *format,
   va_list argptr
);

int _vsnprintf_l(
   char *buffer,
   size_t count,
   const char *format,
   _locale_t locale,
   va_list argptr
);

int _vsnwprintf(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format,
   va_list argptr
);

int _vsnwprintf_l(
   wchar_t *buffer,
   size_t count,
   const wchar_t *format,
   _locale_t locale,
   va_list argptr
);

template <size_t size>
int vsnprintf(
   char (&buffer)[size],
   size_t count,
   const char *format,
   va_list argptr
); // C++ only

template <size_t size>
int _vsnprintf(
   char (&buffer)[size],
   size_t count,
   const char *format,
   va_list argptr
); // C++ only

template <size_t size>
int _vsnprintf_l(
   char (&buffer)[size],
   size_t count,
   const char *format,
   _locale_t locale,
   va_list argptr
); // C++ only

template <size_t size>
int _vsnwprintf(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   va_list argptr
); // C++ only

template <size_t size>
int _vsnwprintf_l(
   wchar_t (&buffer)[size],
   size_t count,
   const wchar_t *format,
   _locale_t locale,
   va_list argptr
); // C++ only

Parametreler

buffer
Çıktı için depolama konumu.

count
Yazacak karakter sayısı üst sınırı. Alınan wchar_tfonksiyonlar için, yazılacak geniş karakter sayısıdır.

format
Biçim belirtimi.

argptr
Bağımsız değişkenler listesinin işaretçisi.

locale
Kullanılacak yerel ayar.

Daha fazla bilgi için, bkz: Biçim belirtimi sözdizimi.

Dönüş değeri

Sonlandırma NULLdahil olmak üzere yazılan karakter sayısı veya bir çıktı hatası oluşursa negatif bir değer.

Ayrıntılar için bkz . Davranış özeti .

Açıklamalar

Bu işlevlerin her biri, bir bağımsız değişken listesine bir işaretçi alır, ardından verileri biçimlendirir ve tarafından countişaret edilen belleğe karakterlere buffer kadar yazar. İşlev vsnprintf , çıktıyı kesse bile her zaman boş bir sonlandırıcı yazar. ve _vsnprintfkullandığınızda_vsnwprintf, arabellek yalnızca sonunda yer varsa (yani, yazılacak karakter sayısı 'den countazsa) null olarak sonlandırılır.

Visual Studio 2015 ve Windows 10'daki UCRT ile başlayarak, vsnprintf artık ile _vsnprintfaynı değildir. İşlev vsnprintf C99 standardına uygundur; _vsnprintf eski kodla geriye dönük uyumluluk için tutulur. Arabellek biterse, vsnprintf arabelleğin sonunu null olarak sonlandırır ve gerekli olan karakter sayısını döndürürken _vsnprintf , arabelleği null olarak sonlandırmaz ve -1 döndürür. Ayrıca, _vsnprintf() arabelleği null olarak sonlandırmadığından çıkışa bir karakter daha ekler.

Önemli

Belirli türdeki güvenlik risklerini önlemek için, bunun format kullanıcı tanımlı bir dize olmadığından emin olun. Daha fazla bilgi için bkz . Arabellek taşmalarından kaçınma. 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 ile legacy_stdio_float_rounding.objbağlayın.

Uyarı

, , _vsnprintf ve çağırırken _vsnprintf_lsonlandırılan null için yer olduğundan emin olmak için, _vsnwprintfbunun _vsnwprintf_l arabellek uzunluğundan kesinlikle daha az olduğundan emin olun ve işlevi çağırmadan önce arabelleği countnull olarak başlatın.

Her vsnprintf zaman bir sonlandırma null yazdığından, count parametre arabelleğin boyutuna eşit olabilir.

Bu işlevlerin soneke _l sahip sürümleri, geçerli iş parçacığı yerel ayarı yerine geçirilen yerel ayar parametresini kullanmaları dışında aynıdır.

C++'da bu işlevler, bu işlevlerin daha yeni ve güvenli karşılıklarını çağıran şablon aşırı yüklemelerine sahiptir. Daha fazla bilgi için bkz. Güvenli şablon aşırı yüklemeleri.

Davranış özeti

Aşağıdaki tablo için:

boyutunun sizeOfBufferolması gerekirbuffer. İş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.
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 char ve arabelleğe alınan wchar_t işlevlere yönelik karakterlere başvururwchar_t.
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ı	Belirtilen biçim dizesini kullanarak karakterleri arabelleğe yazar.	Yazılan karakter sayısı, sonlandırılan boş karakter sayılmaz.	Mevcut Değil	Hayı
Biçimlendirme sırasında kodlama hatası	Dize belirticisi `s`, `S`veya `Z`, biçim belirtimi işleniyorsa işleme durur.	-1	`EILSEQ` (42)	Hayı
Biçimlendirme sırasında kodlama hatası	Karakter tanımlayıcısı `c` veya `C`iş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ı `NULL`dahil değil, yazılan karakter sayısı.	`EILSEQ` (42)	Hayı
`buffer == NULL` ve `count != 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)	Evet
`buffer == NULL` ve `count == 0`	Hiçbir veri yazılmadı	Sonlandırıcı `NULL`dahil olmak üzere yazılabilecek karakter sayısı. Dize ve sonlandırıcı `NULL`için yeterli arabellek alanı ayırmak ve ardından arabelleği doldurmak için işlevi yeniden çağırmak için bu sonucu kullanabilirsiniz.	Mevcut Değil	Hayı
`count == 0`	Hiçbir veri yazılmadı	-1	`ERANGE` (34)	Hayı
`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.	Yazılan karakter sayısı.	Mevcut Değil	Hayı
`count < sizeOfBuffer` ve `len <= count`	Tüm veriler yazılır ve sonlandırıcı `NULL` eklenir.	Sonlandırıcı `NULL`dahil değil, yazılan karakter sayısı.	Mevcut Değil	Hayı
`count < sizeOfBuffer` ve `len > count`	İlk `count-1` karakterlerin ardından null-terminator yazılır.	Yazılmış olabilecek karakter sayısı, null sonlandırıcı dahil olmak üzere çıkış için karakter sayısıyla eşleşmişti `count` .	Mevcut Değil	Hayı
`count >= sizeOfBuffer` ve `len < sizeOfBuffer`	Tüm veriler sonlandırıcı `NULL`ile yazılır.	Sonlandırıcı `NULL`dahil değil, yazılan karakter sayısı.	Mevcut Değil	Hayı
`count >= sizeOfBuffer` ve `len >= sizeOfBuffer`	Güvenli değil: arabelleği takip eden belleğin üzerine yazar.	Sonlandırıcı `NULL`dahil değil, yazılan karakter sayısı.	Mevcut Değil	Hayı
`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)	Evet

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

Genel metin yordamı eşlemeleri

`TCHAR.H` olağan	`_UNICODE` ve `_MBCS` tanımlanmadı	`_MBCS` tanımlanan	`_UNICODE` tanımlanan
`_vsntprintf`	`_vsnprintf`	`_vsnprintf`	`_vsnwprintf`
`_vsntprintf_l`	`_vsnprintf_l`	`_vsnprintf_l`	`_vsnwprintf_l`

Gereksinimler

Rutin	Gerekli başlık (C)	Gerekli başlık (C++)
`vsnprintf`, `_vsnprintf`, `_vsnprintf_l`	`<stdio.h>`	`<stdio.h>` veya `<cstdio>`
`_vsnwprintf`, `_vsnwprintf_l`	`<stdio.h>` veya `<wchar.h>`	`<stdio.h>`, `<wchar.h>`, `<cstdio>`veya `<cwchar>`

, _vsnprintf_vsnprintf_lve _vsnwprintf_vsnwprintf_l işlevleri Microsoft'a özgüdür. Daha fazla uyumluluk bilgisi için bkz . Uyumluluk.

Örnek: ile geniş karakterler kullanın `_vsnwprintf()`

// crt_vsnwprintf.c
// compile by using: cl /W3 crt_vsnwprintf.c

// To turn off error C4996, define this symbol:
#define _CRT_SECURE_NO_WARNINGS

#include <stdio.h>
#include <wtypes.h>

#define BUFFCOUNT (10)

void FormatOutput(LPCWSTR formatstring, ...)
{
    int nSize = 0;
    wchar_t buff[BUFFCOUNT];
    memset(buff, 0, sizeof(buff));
    va_list args;
    va_start(args, formatstring);
    // Note: _vsnwprintf is deprecated; consider vsnwprintf_s instead
    nSize = _vsnwprintf(buff, BUFFCOUNT - 1, formatstring, args); // C4996
    wprintf(L"nSize: %d, buff: %ls\n", nSize, buff);
    va_end(args);
}

int main() {
    FormatOutput(L"%ls %ls", L"Hi", L"there");
    FormatOutput(L"%ls %ls", L"Hi", L"there!");
    FormatOutput(L"%ls %ls", L"Hi", L"there!!");
}

nSize: 8, buff: Hi there
nSize: 9, buff: Hi there!
nSize: -1, buff: Hi there!

Bunun yerine vsnprintf dar dize parametreleriyle birlikte kullanırsanız davranış değişir. Parametre count , arabelleğin tüm boyutu olabilir ve dönüş değeri, yeterince büyük olsaydı count yazılacak karakter sayısıdır:

Örnek: Dar dizelerle kullanın `vsnprintf()`

// crt_vsnprintf.c
// compile by using: cl /W4 crt_vsnprintf.c
#include <stdio.h>
#include <stdarg.h> // for va_list, va_start
#include <string.h> // for memset

#define BUFFCOUNT (10)

void FormatOutput(char* formatstring, ...)
{
    int nSize = 0;
    char buff[BUFFCOUNT];
    memset(buff, 0, sizeof(buff));
    va_list args;
    va_start(args, formatstring);
    nSize = vsnprintf(buff, sizeof(buff), formatstring, args);
    printf("nSize: %d, buff: %s\n", nSize, buff);
    va_end(args);
}

int main() {
    FormatOutput("%s %s", "Hi", "there");   //  8 chars + null
    FormatOutput("%s %s", "Hi", "there!");  //  9 chars + null
    FormatOutput("%s %s", "Hi", "there!!"); // 10 chars + null
}

nSize: 8, buff: Hi there
nSize: 9, buff: Hi there!
nSize: 10, buff: Hi there!

Ayrıca bakınız

Akış G/Ç
vprintf işlevleri
Biçim belirtimi sözdizimi: printf ve wprintf işlevler
fprintf, _fprintf_l, fwprintf, _fwprintf_l
printf, _printf_l, wprintf, _wprintf_l
sprintf, _sprintf_l, swprintf, , _swprintf_l__swprintf_l
va_arg, va_copy, va_end, va_start

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-11-07