`vsnprintf`, `_vsnprintf`, `_vsnprintf_l`, `_vsnwprintf_vsnwprintf_l`

Formázott kimenet írása az argumentumok listájára mutató mutatóval. Ezeknek a funkcióknak biztonságosabb verziói is elérhetők; lásd:vsnprintf_s , _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, . _vsnwprintf_s_l

Szemantika

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

Paraméterek

buffer
A kimenet tárolási helye.

count
Írható karakterek maximális száma. A függvények wchar_tesetében ez az írandó széles karakterek száma.

format
Formátum specifikáció.

argptr
Mutató az argumentumok listájára.

locale
A használni kívánt területi beállítás.

További információ: Formátumspecifikáció szintaxisa.

Visszaadott érték

A beírt karakterek száma, kivéve a befejező NULLkaraktert, vagy a negatív értéket, ha kimeneti hiba lép fel.

Részletekért tekintse meg a viselkedés összefoglalását .

Megjegyzések

Ezen függvények mindegyike egy argumentumlistára mutató mutatót vesz, majd formázza az adatokat, és karaktereket ír count a .buffer A vsnprintf függvény mindig null lezárót ír, még akkor is, ha csonkolja a kimenetet. Ha és _vsnprintf_vsnwprintf, a puffer csak akkor null végződésű, ha van hely a végén (azaz ha az írandó karakterek száma kevesebb, mint count).

A Visual Studio 2015-ben és a Windows 10-ben vsnprintf az UCRT már nem azonos a _vsnprintf. A vsnprintf funkció megfelel a C99 szabványnak; _vsnprintf a régebbi kóddal való visszamenőleges kompatibilitás érdekében megmaradt. A különbség az, hogy ha elfogy a puffer, a null-megszakítja a puffer végét, vsnprintf és visszaadja a szükséges karakterek számát, miközben _vsnprintf nem null-végzi a puffert, és -1-et ad vissza. _vsnprintf() Emellett egy további karaktert is tartalmaz a kimenetben, mert az nem szünteti meg nullhibaként a puffert.

Fontos

Bizonyos típusú biztonsági kockázatok megelőzése érdekében győződjön meg arról, hogy ez format nem felhasználó által definiált sztring. További információ: Puffertúllépések elkerülése. A Windows 10 2004-es verziójától kezdve (19041-es build) a printf függvénycsalád pontosan ábrázolható lebegőpontos számokat nyomtat az IEEE 754 kerekítési szabályainak megfelelően. A Windows korábbi verzióiban az "5" végződésű lebegőpontos számok mindig felfelé kerekülnek. Az IEEE 754 szerint a legközelebbi páros számjegyre kell kerekíteniük (más néven "Banker kerekítése"). Például mindkettőt printf("%1.0f", 1.5) , és printf("%1.0f", 2.5) 2-re kell kerekítenie. Korábban az 1,5 2-et, a 2,5-öt pedig 3-ra kerekítené. Ez a változás csak a pontosan ábrázolható számokat érinti. Például a 2.35 (amely a memóriában ábrázolva közelebb van a 2.35000000000008-hoz) továbbra is 2,4-re kerekít. A függvények által végzett kerekítés mostantól a lebegőpontos kerekítési fesetroundmódot is figyelembe követi. Korábban a kerekítés mindig a viselkedést választotta FE_TONEAREST . Ez a módosítás csak a Visual Studio 2019 16.2-es és újabb verziójával készült programokat érinti. Az örökölt lebegőpontos kerekítési viselkedés használatához csatolja a legacy_stdio_float_rounding.obj.

Megjegyzés:

Annak érdekében, hogy a híváskor _vsnprintflegyen hely a lezáró null értéknek, _vsnprintf_l_vsnwprintf_vsnwprintf_l , és , győződjön meg arról, hogy ez count szigorúan kisebb, mint a puffer hossza, és inicializálja a puffert null értékre a függvény hívása előtt.

Mivel vsnprintf mindig egy lezáró null értéket ír, a count paraméter megegyezhet a puffer méretével.

Ezeknek a függvényeknek az utótaggal ellátott _l verziói azonosak, azzal a különbséggel, hogy az aktuális szál területi beállítása helyett a területi paramétert használják.

A C++ nyelven ezek a függvények sablon-túlterheléssel rendelkeznek, amelyek meghívják a függvények újabb, biztonságos megfelelőit. További információ: A sablon túlterhelésének biztonságossá tételéről.

Viselkedés összefoglalása

A következő táblázathoz:

Legyen sizeOfBuffer a mérete buffer. Ha a függvény puffert char vesz igénybe, a méret bájtban van. Ha a függvény puffert wchar_t vesz igénybe, a méret a 16 bites szavak számát adja meg.
Legyen len a formázott adatok mérete. Ha a függvény puffert char vesz igénybe, a méret bájtban van. Ha a függvény puffert wchar_t vesz igénybe, a méret a 16 bites szavak számát adja meg.
A karakterek a char puffert char használó függvények karaktereire, a wchar_t puffert használó wchar_t függvények karaktereire vonatkoznak.
Az érvénytelen paraméterkezelőről további információt a Paraméterérvényesítés című témakörben talál.

Állapot	Magatartás	Visszaadott érték	`errno`	Érvénytelen paraméterkezelő meghívása
(No changes required, the translation remains "Siker.")	A megadott formátumsztring használatával írja be a karaktereket a pufferbe.	A leírt karakterek száma, a befejező null karaktert nem számítva.	Nincs adat.	Nem
Kódolási hiba a formázás során	Ha a karakterlánc-kijelölő `s`feldolgozása , `S`, vagy `Z`, a formátumspecifikáció feldolgozása leáll.	-1	`EILSEQ` (42)	Nem
Kódolási hiba a formázás során	Ha a karaktermegjelölőt `cC`vagy az érvénytelen karaktert kihagyja a program. Az írott karakterek száma nem növekszik a kihagyott karakterhez, és nem ír rá semmilyen adatot. A formátumspecifikáció feldolgozása folytatódik, miután kihagyta a kijelölőt a kódolási hibával.	Az írott karakterek száma, a befejezést `NULL`nem beleértve.	`EILSEQ` (42)	Nem
`buffer == NULL` és `count != 0`	Ha a végrehajtás az érvénytelen paraméterkezelő végrehajtása után is folytatódik, negatív értéket állít be `errno` és ad vissza.	-1	`EINVAL` (22)	Igen
`buffer == NULL` és `count == 0`	Adatok nem íródnak	Azoknak a karaktereknek a száma, amelyek meg lettek volna írva, és nem tartalmazzák a végződést `NULL`. Ezzel az eredménnyel lefoglalhat elegendő pufferterületet a sztringhez és a befejezéshez, majd újra meghívhatja a függvényt `NULL`a puffer kitöltéséhez.	Nincs adat.	Nem
`count == 0`	Adatok nem íródnak	-1	`ERANGE` (34)	Nem
`count < 0`	Nem biztonságos: a rendszer aláíratlanként kezeli az értéket, ami valószínűleg egy nagy értéket hoz létre, amely felülírja a puffert követő memóriát.	Az írott karakterek száma.	Nincs adat.	Nem
`count < sizeOfBuffer` és `len <= count`	Az összes adat meg van írva, és a program hozzáfűzi a befejezést `NULL` .	Az írott karakterek száma, a befejezést `NULL`nem beleértve.	Nincs adat.	Nem
`count < sizeOfBuffer` és `len > count`	Az első `count-1` karaktereket null terminátor követi.	A megírt karakterek száma megfelelt volna `count` a kimenethez tartozó karakterek számának, a null-terminátort nem beleértve.	Nincs adat.	Nem
`count >= sizeOfBuffer` és `len < sizeOfBuffer`	Az összes adat meg van írva egy végződéssel `NULL`.	Az írott karakterek száma, a befejezést `NULL`nem beleértve.	Nincs adat.	Nem
`count >= sizeOfBuffer` és `len >= sizeOfBuffer`	Nem biztonságos: felülírja a puffert követő memóriát.	Az írott karakterek száma, a befejezést `NULL`nem beleértve.	Nincs adat.	Nem
`format == NULL`	Nincs adat megírva. Ha a végrehajtás az érvénytelen paraméterkezelő végrehajtása után is folytatódik, negatív értéket állít be `errno` és ad vissza.	-1	`EINVAL` (22)	Igen

Ezekről és más hibakódokról további információt a _doserrno, errno, _sys_errlistés _sys_nerr.

Általános szöveges rutinleképezések

`TCHAR.H` rutin	`_UNICODE` és `_MBCS` nincs definiálva	`_MBCS` definiálva	`_UNICODE` definiálva
`_vsntprintf`	`_vsnprintf`	`_vsnprintf`	`_vsnwprintf`
`_vsntprintf_l`	`_vsnprintf_l`	`_vsnprintf_l`	`_vsnwprintf_l`

Követelmények

Rutin	Kötelező fejléc (C)	Kötelező fejléc (C++)
\, \, \	`<stdio.h>`	`<stdio.h>` vagy `<cstdio>`
`_vsnwprintf`, `_vsnwprintf_l`	`<stdio.h>` vagy `<wchar.h>`	`<stdio.h>`, `<wchar.h>`, `<cstdio>`vagy `<cwchar>`

A _vsnprintf, _vsnprintf_lés _vsnwprintf a _vsnwprintf_l függvények Microsoft-specifikusak. További kompatibilitási információkért lásd: Kompatibilitás.

Példa: Széles karakterek használata a következővel: `_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!

A viselkedés megváltozik, ha ehelyett a vsnprintf parancsot használja a keskeny karakterláncú paraméterekkel együtt. A count paraméter lehet a puffer teljes mérete, a visszatérési érték pedig az a karakterszám, amelyet akkor írtak volna, ha count elég nagy lenne:

Példa: Használat `vsnprintf()` keskeny karakterláncokkal

// 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!

Lásd még

Stream I/O-
vprintf funkciók
Formátumspecifikáció szintaxisa: printf és függvények wprintf
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_endva_start

Visszajelzés

Hasznosnak találta ezt az oldalt?

Last updated on 2025-11-07