`mbsrtowcs_s`

Artikel
10/12/2023

Mengonversi string karakter multibyte di lokal saat ini ke representasi string karakter lebarnya. Versi mbsrtowcs dengan peningkatan keamanan seperti yang dijelaskan dalam Fitur keamanan di CRT.

Sintaks

errno_t mbsrtowcs_s(
   size_t * pReturnValue,
   wchar_t * wcstr,
   size_t sizeInWords,
   const char ** mbstr,
   size_t count,
   mbstate_t * mbstate
);
template <size_t size>
errno_t mbsrtowcs_s(
   size_t * pReturnValue,
   wchar_t (&wcstr)[size],
   const char ** mbstr,
   size_t count,
   mbstate_t * mbstate
); // C++ only

Parameter

pReturnValue
Jumlah karakter yang dikonversi.

wcstr
Alamat buffer untuk menyimpan string karakter lebar yang dikonversi yang dihasilkan.

sizeInWords
Ukuran wcstr dalam kata-kata (karakter lebar).

mbstr
Penunjuk tidak langsung ke lokasi string karakter multibyte yang akan dikonversi.

count
Jumlah maksimum karakter lebar untuk disimpan dalam wcstr buffer, tidak termasuk penghentian null, atau _TRUNCATE.

mbstate
Penunjuk ke mbstate_t objek status konversi. Jika nilai ini adalah penunjuk null, objek status konversi internal statis digunakan. Karena objek internal mbstate_t tidak aman untuk utas, kami sarankan Anda selalu meneruskan parameter Anda sendiri mbstate .

Nilai hasil

Nol jika konversi berhasil, atau kode kesalahan pada kegagalan.

Kondisi kesalahan	Mengembalikan nilai dan `errno`
`wcstr` adalah penunjuk null dan `sizeInWords`> 0	`EINVAL`
`mbstr` adalah penunjuk null	`EINVAL`
String secara tidak langsung menunjuk ke dengan `mbstr` berisi urutan multibyte yang tidak valid untuk lokal saat ini.	`EILSEQ`
Buffer tujuan terlalu kecil untuk berisi string yang dikonversi (kecuali `count` ; `_TRUNCATE`untuk informasi selengkapnya, lihat Keterangan)	`ERANGE`

Jika salah satu kondisi ini terjadi, pengecualian parameter yang tidak valid dipanggil seperti yang dijelaskan dalam Validasi parameter . Jika eksekusi diizinkan untuk melanjutkan, fungsi mengembalikan kode kesalahan dan mengatur errno seperti yang ditunjukkan dalam tabel.

Keterangan

Fungsi ini mbsrtowcs_s mengonversi string karakter multibyte yang secara tidak langsung diarahkan ke mbstr menjadi karakter lebar yang disimpan dalam buffer yang diarahkan oleh wcstr, dengan menggunakan status konversi yang terkandung dalam mbstate. Konversi akan berlanjut untuk setiap karakter hingga salah satu kondisi ini terpenuhi:

Karakter null multibyte ditemui
Ditemui karakter multibyte yang tidak valid
Jumlah karakter lebar yang wcstr disimpan dalam buffer sama dengan count.

String wcstr tujuan selalu dihentikan null, bahkan ketika ada kesalahan, kecuali wcstr jika merupakan penunjuk null.

Jika count adalah nilai _TRUNCATEkhusus , mbsrtowcs_s mengonversi string sebanyak yang akan masuk ke dalam buffer tujuan, sambil tetap meninggalkan ruang untuk terminator null.

Jika mbsrtowcs_s berhasil mengonversi string sumber, string sumber menempatkan ukuran dalam karakter luas string yang dikonversi dan terminator null menjadi *pReturnValue, yang disediakan pReturnValue bukan penunjuk null. Ukuran dihitung bahkan jika wcstr argumen adalah pointer null, yang memungkinkan Anda menentukan ukuran buffer yang diperlukan. Jika wcstr adalah penunjuk null, count diabaikan.

Jika wcstr bukan penunjuk null, objek penunjuk yang diakhiri oleh mbstr ditetapkan penunjuk null jika konversi berhenti karena karakter null yang mengakhiri tercapai. Jika tidak, alamat ditetapkan hanya melewati karakter multibyte terakhir yang dikonversi, jika ada. Ini memungkinkan panggilan fungsi berikutnya untuk memulai ulang konversi di mana panggilan ini berhenti.

Jika mbstate adalah penunjuk null, objek statis status konversi internal mbstate_t pustaka digunakan. Karena objek statis internal ini tidak aman untuk utas, kami sarankan Anda meneruskan nilai Anda sendiri mbstate .

Jika mbsrtowcs_s menemukan karakter multibyte yang tidak valid di lokal saat ini, karakter tersebut menempatkan -1 di *pReturnValue, mengatur buffer wcstr tujuan ke string kosong, mengatur errno ke EILSEQ, dan mengembalikan EILSEQ.

Jika urutan menunjuk ke oleh mbstr dan wcstr tumpang tindih, perilaku mbsrtowcs_s tidak terdefinisi. mbsrtowcs_s dipengaruhi oleh LC_TYPE kategori lokal saat ini.

Penting

Pastikan dan wcstrmbstr jangan tumpang tindih, dan itu mencerminkan jumlah karakter multibyte yang count akan dikonversi dengan benar.

Fungsi mbsrtowcs_s ini berbeda dari mbstowcs_s, _mbstowcs_s_l dengan restartability-nya. Status konversi disimpan dalam mbstate untuk panggilan berikutnya ke fungsi yang sama atau dapat dimulai ulang lainnya. Hasil tidak terdefinisi saat mencampur penggunaan fungsi yang dapat dimulai ulang dan tidak dapat ditarik kembali. Misalnya, aplikasi harus menggunakan mbsrlen alih-alih mbslen, jika panggilan berikutnya digunakan mbsrtowcs_s alih-alih mbstowcs_s.

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

Secara default, status global fungsi ini dicakup ke aplikasi. Untuk mengubah perilaku ini, lihat Status global di CRT.

Pengecualian

Fungsi mbsrtowcs_s ini aman multithread jika tidak ada fungsi dalam panggilan utas setlocale saat ini selama fungsi ini dijalankan dan mbstate argumen bukan penunjuk null.

Persyaratan

Rutin	Header yang diperlukan
`mbsrtowcs_s`	<wchar.h>

Bagikan melalui