`wcsrtombs_s`

Makale
10/12/2023

Geniş karakter dizesini çok baytlı 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üwcsrtombs.

Sözdizimi

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

Parametreler

pReturnValue
Dönüştürülen dizenin bayt cinsinden boyutu (null sonlandırıcı dahil).

mbstr
Sonuçta dönüştürülen çok baytlı karakter dizesi için arabelleğin adresi.

sizeInBytes
Arabelleğin mbstr bayt cinsinden boyutu.

wcstr
Dönüştürülecek geniş karakter dizesini gösterir.

count
Arabellekte _TRUNCATEveya içinde mbstr depolanacak en fazla bayt sayısı.

mbstate
Dönüştürme durumu nesnesinin mbstate_t işaretçisi.

Dönüş değeri

Başarılı olursa sıfır, hata durumunda bir hata kodu.

Hata koşulu	Dönüş değeri ve `errno`
`mbstr` ve `NULL` `sizeInBytes`> 0	`EINVAL`
`wcstr` dir `NULL`	`EINVAL`
Hedef arabellek dönüştürülen dizeyi içeremeyecek kadar küçük (değilse `count` `_TRUNCATE`, aşağıdaki Açıklamalar'a bakın)	`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, wcsrtombs_s içinde bulunan mbstatedönüştürme durumunu kullanarak, tarafından işaret edilen wcstr geniş karakter dizesini, tarafından işaret edilen arabellekte depolanan çok baytlı karakterlere mbstrdönüştürür. Dönüştürme, bu koşullardan biri karşılanıncaya kadar her karakter için devam eder:

Null geniş karakterle karşılaşıldı
Dönüştürülemez geniş bir karakterle karşılaşılır
Arabellekte mbstr depolanan bayt sayısı eşittir count.

Hedef dize her zaman null olarak sonlandırılır (hata olsa bile).

özel değer _TRUNCATEisecount, wcsrtombs_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 wcsrtombs_s , boyutu null sonlandırıcı da dahil olmak üzere dönüştürülen dizenin bayt cinsinden değerini içine *pReturnValue yerleştirir (sağlanmamıştır pReturnValue NULL). Bağımsız değişken NULLolsa mbstr bile boyut hesaplanır; gerekli arabellek boyutunu belirlemek için bir yol sağlar. ise mbstr NULLcount yoksayılır.

Çok baytlı bir karaktere dönüştüremediğiniz geniş bir karakterle karşılaşırsawcsrtombs_s, içine -1 *pReturnValueekler, hedef arabelleği boş bir dizeye ayarlar, olarak EILSEQayarlar errno ve döndürürEILSEQ.

Tarafından işaret edilen wcstr ve mbstr çakışan diziler, davranışı wcsrtombs_s tanımlanmamıştır. wcsrtombs_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 geniş karakter sayısını doğru yansıttığından emin olun.

İşlev, wcsrtombs_s yeniden başlatılabilirliğine göre işlevinden _wcstombs_s_lwcstombs_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ıldıysa, bir uygulama yerine wcstombs_skullanır wcsrlen wcslen.wcsrtombs_s

C++'ta bu işlevlerin kullanılması şablon aşırı yüklemeleriyle basitleştirilir; aşırı yüklemeler arabellek uzunluğunu otomatik olarak çıkarabilir (boyut bağımsız değişkeni belirtme gereksinimini ortadan kaldırır) ve eski, güvenli olmayan işlevleri yeni ve güvenli karşılıklarıyla otomatik olarak değiştirebilir. 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 wcsrtombs_s işlev yürütülürken geçerli iş parçacığı setlocale çağrılarında işlev olmadığı ve mbstate null olduğu sürece işlev çok iş parçacıklı güvenlidir.

Örnek

// crt_wcsrtombs_s.cpp
//
// This code example converts a wide
// character string into a multibyte
// character string.
//

#include <stdio.h>
#include <memory.h>
#include <wchar.h>
#include <errno.h>

#define MB_BUFFER_SIZE 100

int main()
{
    const wchar_t   wcString[] =
                    {L"Every good boy does fine."};
    const wchar_t   *wcsIndirectString = wcString;
    char            mbString[MB_BUFFER_SIZE];
    size_t          countConverted;
    errno_t         err;
    mbstate_t       mbstate;

    // Reset to initial shift state
    ::memset((void*)&mbstate, 0, sizeof(mbstate));

    err = wcsrtombs_s(&countConverted, mbString, MB_BUFFER_SIZE,
                      &wcsIndirectString, MB_BUFFER_SIZE, &mbstate);
    if (err == EILSEQ)
    {
        printf( "An encoding error was detected in the string.\n" );
    }
    else
    {
        printf( "The string was successfully converted.\n" );
    }
}

The string was successfully converted.

Gereksinimler

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

Ayrıca bkz.

Veri dönüştürme
Yerel ayar
Çok baytlı karakter dizilerinin yorumlanması
wcrtomb
wcrtomb_s
wctomb, _wctomb_l
wcstombs, _wcstombs_l
mbsinit

Aracılığıyla paylaş