vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l

Tulis output yang diformat menggunakan penunjuk ke daftar argumen. Fungsi-fungsi ini adalah versi vsnprintf, , _vsnprintf_vsnprintf_l, _vsnwprintf,_vsnwprintf_ldengan peningkatan keamanan seperti yang dijelaskan dalam Fitur keamanan di CRT.

Sintaks

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

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

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

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

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

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

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

Parameter

buffer
Lokasi penyimpanan untuk output.

sizeOfBuffer
Ukuran buffer untuk output. Ukuran dalam byte untuk fungsi yang mengambil char, dan kata-kata untuk mereka yang mengambil wchar_t.

count
Jumlah maksimum karakter untuk ditulis tidak termasuk yang mengakhiri NULL. Untuk fungsi yang mengambil wchar_t, jumlah karakter lebar yang akan ditulis. Atau _TRUNCATE.

format
Spesifikasi format.

argptr
Penunjuk ke daftar argumen.

locale
Lokal yang digunakan saat memformat output.

Untuk informasi selengkapnya, lihat Spesifikasi format.

Nilai hasil

Jumlah karakter yang ditulis, tidak termasuk penghentian NULL, atau nilai negatif jika terjadi kesalahan output.

Lihat Ringkasan perilaku untuk detailnya.

Keterangan

vsnprintf_s identik dengan _vsnprintf_s dan disertakan agar sesuai dengan standar ANSI. _vnsprintf dipertahankan untuk kompatibilitas mundur.

Masing-masing fungsi ini mengambil penunjuk ke daftar argumen, lalu memformat dan menulis hingga count karakter data yang diberikan ke memori yang diarahkan oleh buffer dan menambahkan null yang mengakhiri.

Versi fungsi-fungsi ini dengan _l akhiran identik kecuali mereka menggunakan parameter lokal yang diteruskan alih-alih lokal utas saat ini.

Ringkasan perilaku

Untuk tabel berikut:

• Biarkan len menjadi ukuran data yang diformat. Jika fungsi mengambil char buffer, ukurannya dalam byte. Jika fungsi mengambil wchar_t buffer, ukuran menentukan jumlah kata 16-bit.
• Karakter merujuk ke char karakter untuk fungsi yang mengambil char buffer, dan ke wchar_t karakter untuk fungsi yang mengambil wchar_t buffer.
• Untuk informasi selengkapnya tentang handler parameter yang tidak valid, lihat Validasi Parameter.

Kondisi	Perilaku	Nilai hasil	errno	Memanggil handler parameter yang tidak valid
Sukses	Menulis karakter ke dalam buffer menggunakan string format yang ditentukan	Jumlah karakter yang ditulis	T/A	Tidak
Kesalahan pengodean selama pemformatan	Jika pemrosesan penentu sstring , , Satau Z, pemrosesan spesifikasi format berhenti.	-1	EILSEQ (42)	Tidak
Kesalahan pengodean selama pemformatan	Jika memproses penentu c karakter atau C, karakter yang tidak valid dilewati. Jumlah karakter yang ditulis tidak bertahap untuk karakter yang dilewati, atau data apa pun yang ditulis untuknya. Memproses spesifikasi format berlanjut setelah melewati penentu dengan kesalahan pengodean.	Jumlah karakter yang ditulis, tidak termasuk yang mengakhiri NULL.	EILSEQ (42)	Tidak
buffer == NULLdan dan sizeOfBuffer == 0count == 0	Tidak ada data yang ditulis.	0	T/A	Tidak
buffer == NULLdan atau sizeOfBuffer != 0count != 0	Jika eksekusi berlanjut setelah handler parameter tidak valid dijalankan, set errno dan mengembalikan nilai negatif.	-1	EINVAL (22)	Ya
buffer != NULL dan sizeOfBuffer == 0	Tidak ada data yang ditulis. Jika eksekusi berlanjut setelah handler parameter tidak valid dijalankan, set errno dan mengembalikan nilai negatif.	-1	EINVAL (22)	Ya
count == 0	Tidak menulis data apa pun dan mengembalikan jumlah karakter yang akan ditulis, tidak termasuk penghentian NULL.	Jumlah karakter yang akan ditulis tidak termasuk penghentian NULL.	T/A	Tidak
count < 0	Tidak aman: nilai diperlakukan sebagai tidak ditandatangani, kemungkinan menciptakan nilai besar yang menghasilkan penimpaan memori yang mengikuti buffer.	Jumlah karakter yang ditulis, tidak termasuk yang mengakhiri NULL.	T/A	Tidak
count < sizeOfBuffer dan len <= count	Semua data ditulis dan penghentian NULL ditambahkan.	Jumlah karakter yang ditulis.	T/A	Tidak
count < sizeOfBuffer dan len > count	Karakter pertama count ditulis.	-1	T/A	Tidak
count >= sizeOfBuffer dan len < sizeOfBuffer	Semua data ditulis dengan penghentian NULL.	Jumlah karakter yang ditulis, tidak termasuk yang mengakhiri NULL.	T/A	Tidak
count >= sizeOfBufferdan dan len >= sizeOfBuffercount != _TRUNCATE	Jika eksekusi berlanjut setelah handler parameter tidak valid dijalankan, set errno, set buffer[0] == NULL, dan mengembalikan nilai negatif.	-1	ERANGE (34)	Ya
count == _TRUNCATE dan len >= sizeOfBuffer	Menulis sebanyak string yang sesuai dengan buffer, termasuk penghentian NULL.	-1	T/A	Tidak
count == _TRUNCATE dan len < sizeOfBuffer	Menulis seluruh string ke dalam buffer dengan mengakhiri NULL.	Jumlah karakter yang ditulis.	T/A	Tidak
format == NULL	Tidak ada data yang ditulis. Jika eksekusi berlanjut setelah handler parameter tidak valid dijalankan, set errno dan mengembalikan nilai negatif.	-1	EINVAL (22)	Ya

Untuk informasi tentang kode kesalahan ini dan lainnya, lihat _doserrno, , errno_sys_errlist, dan _sys_nerr.

Penting

Pastikan itu format bukan string yang ditentukan pengguna. Untuk informasi selengkapnya, lihat Menghindari overruns buffer. Mulai Windows 10 versi 2004 (build 19041), printf keluarga fungsi mencetak angka titik mengambang yang persis dapat diwakili sesuai dengan aturan IEEE 754 untuk pembulatan. Di versi Windows sebelumnya, angka titik pecahan yang persis dapat diwakili yang berakhiran '5' akan selalu dibulatkan. IEEE 754 menyatakan bahwa mereka harus membulatkan ke digit terdekat bahkan (juga dikenal sebagai "Pembulatan Bankir"). Misalnya, dan printf("%1.0f", 1.5)printf("%1.0f", 2.5) harus membulatkan ke 2. Sebelumnya, 1,5 akan membulatkan ke 2 dan 2,5 akan dibulatkan ke 3. Perubahan ini hanya memengaruhi angka yang tepat yang dapat diwakili. Misalnya, 2,35 (yang, ketika diwakili dalam memori, lebih dekat ke 2,3500000000000000008) terus membulatkan ke atas hingga 2,4. Pembulatan yang dilakukan oleh fungsi-fungsi ini sekarang juga menghormati mode pembulatan titik mengambang yang ditetapkan oleh fesetround. Sebelumnya, pembulatan selalu memilih FE_TONEAREST perilaku. Perubahan ini hanya memengaruhi program yang dibuat menggunakan Visual Studio 2019 versi 16.2 dan yang lebih baru. Untuk menggunakan perilaku pembulatan titik mengambang warisan, tautkan dengan 'legacy_stdio_float_rounding.obj'.

Catatan

Untuk memastikan bahwa ada ruang untuk penghentian null, pastikan itu count benar-benar kurang dari panjang buffer, atau gunakan _TRUNCATE.

Di C++, menggunakan fungsi-fungsi ini disederhanakan oleh kelebihan beban templat; kelebihan beban dapat menyimpulkan panjang buffer secara otomatis (menghilangkan kebutuhan untuk menentukan argumen ukuran) dan mereka dapat secara otomatis mengganti fungsi lama yang tidak aman dengan rekan-rekan yang lebih baru dan aman. Untuk informasi selengkapnya, lihat Mengamankan kelebihan beban templat.

Tip

Jika Anda mendapatkan kesalahan eksternal _vsnprintf_s yang tidak ditentukan dan menggunakan Universal C Runtime, tambahkan legacy_stdio_definitions.lib ke kumpulan pustaka yang akan ditautkan. Universal C Runtime tidak mengekspor fungsi ini secara langsung dan sebaliknya didefinisikan sebaris dalam <stdio.h>. Untuk informasi selengkapnya, lihat Gambaran umum potensi masalah peningkatan dan perubahan kesuaian Visual Studio 2015.

Pemetaan rutin teks generik

TCHAR.H Rutin	_UNICODE dan _MBCS tidak ditentukan	_MBCS Didefinisikan	_UNICODE Didefinisikan
_vsntprintf_s	_vsnprintf_s	_vsnprintf_s	_vsnwprintf_s
_vsntprintf_s_l	_vsnprintf_s_l	_vsnprintf_s_l	_vsnwprintf_s_l

Persyaratan

Rutin	Header yang diperlukan	Header opsional
vsnprintf_s	<stdio.h> dan <stdarg.h>	<varargs.h>*
_vsnprintf_s, _vsnprintf_s_l	<stdio.h> dan <stdarg.h>	<varargs.h>*
_vsnwprintf_s, _vsnwprintf_s_l	<stdio.h> atau <wchar.h>, dan <stdarg.h>	<varargs.h>*

* Diperlukan untuk kompatibilitas UNIX V.

Untuk informasi kompatibilitas selengkapnya, lihat Kompatibilitas.

Contoh

// crt_vsnprintf_s.cpp
#include <stdio.h>
#include <wtypes.h>

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

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

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

Baca juga

Streaming I/O
vprintf Fungsi
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