`mbsrtowcs_s`

Makale
10/12/2023

Geçerli yerel ayardaki çok baytlı bir karakter dizesini geniş karakter dizesi gösterimine dönüştürün. CRT'deki Güvenlik özellikleri bölümünde açıklandığı gibi güvenlik geliştirmeleri içeren sürümümbsrtowcs.

Sözdizimi

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

Parametreler

pReturnValue
Dönüştürülen karakter sayısı.

wcstr
Sonuçta dönüştürülen geniş karakter dizesini depolamak için arabellek adresi.

sizeInWords
Sözcüklerin wcstr boyutu (geniş karakterler).

mbstr
Dönüştürülecek çok baytlı karakter dizesinin konumuna dolaylı işaretçi.

count
Sonlandırıcı null veya _TRUNCATEdahil olmak üzere arabellekte wcstr depolanmış en fazla geniş karakter sayısı.

mbstate
Dönüştürme durumu nesnesinin mbstate_t işaretçisi. Bu değer null bir işaretçiyse, statik bir iç dönüştürme durumu nesnesi kullanılır. İç mbstate_t nesne iş parçacığı açısından güvenli olmadığından her zaman kendi mbstate parametrenizi geçirmenizi öneririz.

Dönüş değeri

Dönüştürme başarılı olursa sıfır veya hata durumunda bir hata kodu.

Hata koşulu	Dönüş değeri ve `errno`
`wcstr` null işaretçi ve `sizeInWords`> 0	`EINVAL`
`mbstr` null işaretçidir	`EINVAL`
tarafından dolaylı olarak işaret edilen `mbstr` dize, geçerli yerel ayar için geçerli olmayan çok baytlı bir dizi içeriyor.	`EILSEQ`
Hedef arabellek dönüştürülen dizeyi içeremeyecek kadar küçüktür (değilse `count``_TRUNCATE`; daha fazla bilgi için bkz. Açıklamalar)	`ERANGE`

Bu koşullardan herhangi biri oluşursa, parametre doğrulaması bölümünde açıklandığı gibi geçersiz parametre özel durumu çağrılır. Yürütmenin devam etmesi için izin verilirse işlev bir hata kodu döndürür ve tabloda gösterildiği gibi ayarlar errno .

Açıklamalar

işlevi, mbsrtowcs_s içinde yer alan mbstatedönüştürme durumunu kullanarak dolaylı olarak tarafından mbstr işaret edilen çok baytlı bir karakter dizesini tarafından işaret edilen arabellekte depolanan geniş karakterlere wcstrdönüştürür. Dönüştürme, bu koşullardan biri karşılanıncaya kadar her karakter için devam eder:

Çok baytlı null karakterle karşılaşıldı
Geçersiz bir çok baytlı karakterle karşılaşıldı
Arabellekte wcstr depolanan geniş karakter sayısı eşittir count.

Hedef dize wcstr , bir hata olduğunda bile null işaretçisi olmadığı sürece wcstr her zaman null olarak sonlandırılır.

özel değer _TRUNCATEisecount, mbsrtowcs_s hedef arabelleğe sığacak kadar dizeyi dönüştürür ve null sonlandırıcı için yer bırakmaya devam eder.

Kaynak dizeyi başarıyla dönüştürürse mbsrtowcs_s , boyutu dönüştürülen dizenin geniş karakterlerine ve null sonlandırıcıya yerleştirir *pReturnValue; sağlanan pReturnValue null işaretçi değildir. Bağımsız değişken null bir işaretçi olsa wcstr bile boyut hesaplanır ve bu da gerekli arabellek boyutunu belirlemenize olanak tanır. Null işaretçiyse wcstr yoksayılır count .

Null işaretçi değilse wcstr , tarafından işaret edilen işaretçi nesnesine mbstr , sonlandırıcı bir null karaktere ulaşıldığı için dönüştürme durdurulursa null işaretçi atanır. Aksi takdirde, adrese dönüştürülen son çok baytlı karakterin hemen sonundan (varsa) atanır. Bu çağrının durdurulduğu dönüştürmeyi yeniden başlatmak için sonraki bir işlev çağrısına izin verir.

Boş bir işaretçiyse mbstate , kitaplık iç mbstate_t dönüştürme durumu statik nesnesi kullanılır. Bu iç statik nesne iş parçacığı açısından güvenli olmadığından, kendi mbstate değerinizi geçirmenizi öneririz.

Geçerli yerel ayarda geçerli olmayan çok baytlı bir karakterle karşılaşırsa mbsrtowcs_s , içine -1 *pReturnValueekler, hedef arabelleği wcstr boş bir dizeye ayarlar, olarak EILSEQayarlar errno ve döndürürEILSEQ.

Tarafından işaret edilen mbstr ve wcstr çakışan diziler, davranışı mbsrtowcs_s tanımlanmamıştır. mbsrtowcs_s geçerli yerel ayarın LC_TYPE kategorisinden etkilenir.

Önemli

ve mbstr değerlerinin wcstr çakışmadığından ve count dönüştürülecek çok baytlı karakter sayısını doğru yansıttığından emin olun.

İşlev, mbsrtowcs_s yeniden başlatılabilirliğine göre işlevinden _mbstowcs_s_lmbstowcs_s farklıdır. Dönüştürme durumu, aynı veya diğer yeniden başlatılabilir işlevlere yapılan sonraki çağrılar için içinde mbstate depolanır. Yeniden başlatılabilir ve yeniden başlatılamayan işlevlerin kullanımı karıştırılırken sonuçlar tanımlanmamıştır. Örneğin, yerine sonraki bir çağrısı kullanılıyorsa, bir uygulama yerine mbstowcs_skullanmalıdır mbsrlenmbslen.mbsrtowcs_s

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

Varsayılan olarak, bu işlevin genel durumunun kapsamı uygulama olarak belirlenmiştir. Bu davranışı değiştirmek için bkz. CRT'de Genel durum.

Özel durumlar

Bu mbsrtowcs_s işlev yürütülürken bağımsız mbstate değişken null işaretçi olmadığı sürece geçerli iş parçacığında hiçbir işlev çağrılmazsa setlocale işlev çok iş parçacıklı güvenlidir.

Gereksinimler

Yordam	Gerekli başlık
`mbsrtowcs_s`	<wchar.h>

Ayrıca bkz.

Veri dönüştürme
Yerel ayar
Çok baytlı karakter dizilerinin yorumlanması
mbrtowc
mbtowc, _mbtowc_l
mbstowcs_s, _mbstowcs_s_l
mbsinit

Aracılığıyla paylaş